archspec 0.3.0 → 0.4.0

data/lib/archspec/dsl.rb

@@ -1,26 +1,105 @@
 # frozen_string_literal: true
 
+require 'pathname'
+
 module ArchSpec
+  # The ArchSpec DSL.
+  #
+  # An +Archspec.rb+ file is evaluated in this context, so every method here is
+  # a top-level call in that file.
   module DSL
+    # The top-level DSL. Declare the project, its components, an architecture
+    # preset, and global rules.
+    #
+    #   root "."
+    #   source "app/**/*.rb", "lib/**/*.rb"
+    #   ignore "app/legacy/**/*.rb"
+    #   todo "archspec_todo.yml"
+    #
+    #   component :models, in: "app/models/**/*.rb"
+    #   component :controllers, in: "app/controllers/**/*.rb"
+    #   models.cannot_use :controllers
+    #
+    # Declaring a component defines a reader for it, so +models+ and
+    # +controllers+ above return an ArchSpec::DSL::ComponentProxy you attach
+    # rules to.
     module Context
+      # Sets or reads the project root that file patterns resolve against.
+      # Defaults to the directory of the +Archspec.rb+ file.
       def root(path = nil)
         return root_path unless path
 
         self.root_path = path.to_s
       end
 
+      # Adds glob patterns for the files ArchSpec parses. Defaults cover
+      # +app+, +lib+, packs, and engines. Component patterns are always
+      # analyzed, so most projects never need this.
       def source(*patterns)
         add_source_patterns(patterns)
       end
 
+      # Adds glob patterns for files to skip. Combines with the built-in
+      # ignores for +.git+, +tmp+, +vendor+, and +node_modules+.
       def ignore(*patterns)
         add_ignore_patterns(patterns)
       end
 
-      def baseline(path = '.archspec_todo.yml')
-        self.baseline_path = path.to_s
+      # Points at a todo file of accepted violations. Diagnostics recorded there
+      # are subtracted from future runs, so you can adopt ArchSpec in an existing
+      # app without fixing everything first, then burn the list down.
+      #
+      #   todo "archspec_todo.yml"
+      #
+      # Write or refresh it with <tt>archspec check --update-todo</tt>.
+      def todo(path = 'archspec_todo.yml')
+        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,
+      # so it does not matter where +archspec+ is run from.
+      #
+      #   each_directory "engines/*" do |name, path|
+      #     component name, in: "#{path}/**/*.rb"
+      #   end
+      #
+      # Yields the directory basename and its root-relative path. Returns the
+      # <tt>[name, path]</tt> pairs when called without a block.
+      def each_directory(glob)
+        base = absolute_root
+        pairs = Dir.glob(File.join(base, glob)).select { |path| File.directory?(path) }.sort.map do |absolute|
+          [File.basename(absolute), Pathname(absolute).relative_path_from(Pathname(base)).to_s]
+        end
+
+        return pairs unless block_given?
+
+        pairs.each { |name, path| yield(name, path) }
+      end
+
+      # Declares a component: a named set of files, matched by glob, namespace,
+      # or explicit constant.
+      #
+      #   component :services, in: "app/services/**/*.rb"
+      #   component :billing, namespace: "Billing"
+      #   component :legacy, constants: %w[OldReport OldExport]
+      #
+      # 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)
@@ -31,18 +110,44 @@ module ArchSpec
       alias layer component
       alias role component
 
+      # Applies a bundled architecture preset, defining its components and
+      # rules together.
+      #
+      #   architecture :rails
+      #   architecture :hexagonal
+      #   architecture :modular_monolith, components: { ... }, allow: { ... }
+      #
+      # See ArchSpec::Architectures for every preset and its options.
       def architecture(name, **options)
         Architectures.apply(name, self, **options)
       end
 
+      # 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]
+      #
+      # Rule id: +dependencies.no_cycles+.
       def no_cycles!(among: nil)
         add_rule(Rules::NoCyclesRule.new(among: among))
       end
 
-      def verify_zeitwerk_names!
-        add_rule(Rules::ZeitwerkNamingRule.new)
+      # 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.
       def rule(rule)
         add_rule(rule)
       end
@@ -58,6 +163,11 @@ module ArchSpec
       end
     end
 
+    # A handle to one component, returned by ArchSpec::DSL::Context#component
+    # and by calling a declared component's name. Rule methods return +self+, so
+    # they chain.
+    #
+    #   services.cannot_use(:controllers).cannot_call(:render, receiver: :none)
     class ComponentProxy
       attr_reader :definition, :name
 
@@ -66,6 +176,13 @@ module ArchSpec
         @name = name.to_sym
       end
 
+      # Allowlists the components this one may depend on. A reference to any
+      # other declared component fails.
+      #
+      #   controllers.can_use :models, :services
+      #
+      # +only_depend_on+ and +must_only_depend_on+ are aliases.
+      # Rule id: +dependencies.allow+.
       def can_use(*targets)
         add_rule(Rules::AllowDependenciesRule.new(name, targets))
         self
@@ -74,36 +191,126 @@ module ArchSpec
       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.
+      #
+      #   models.cannot_use :controllers, :helpers
+      #
+      # Rule id: +dependencies.forbid+.
       def cannot_use(*targets)
         add_rule(Rules::ForbidDependenciesRule.new(name, targets))
         self
       end
 
-      def cannot_call(*methods)
-        add_rule(Rules::CannotCallRule.new(name, methods))
+      # Allowlists the components that may reference this one, the inverse of
+      # #can_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
+      #
+      # Rule id: +dependencies.consumers+.
+      def can_only_be_used_by(*consumers)
+        add_rule(Rules::AllowedConsumersRule.new(name, consumers))
         self
       end
 
+      # Forbids calling the named methods. By default any receiver matches, so
+      # this catches +record.update+ and +cache.update+ alike. Pass
+      # <tt>receiver: :none</tt> to match only bare, implicit-+self+ calls, which
+      # is how the Rails presets keep the controller API out of models.
+      #
+      #   queries.cannot_call :save, :update, :destroy
+      #   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.
+      # Rule id: +methods.forbid+.
+      def cannot_call(*methods, receiver: :any)
+        add_rule(Rules::CannotCallRule.new(name, methods, receiver: receiver))
+        self
+      end
+
+      # Forbids defining the named methods in this component. Use it when the
+      # method name itself is a design smell there, such as +call+ on a
+      # component that should not hold command objects.
+      #
+      #   models.cannot_define :call
+      #
+      # Rule id: +methods.define_forbid+.
       def cannot_define(*methods)
         add_rule(Rules::CannotDefineMethodRule.new(name, methods))
         self
       end
 
+      # Forbids the one-shot <tt>Thing.new(...).call</tt> pattern, where a class
+      # is instantiated and immediately invoked. Use it to steer a component
+      # toward plain methods over anonymous command objects.
+      #
+      # Rule id: +objects.instantiate_and_invoke_forbid+.
       def cannot_instantiate_and_invoke
         add_rule(Rules::CannotInstantiateAndInvokeRule.new(name))
         self
       end
 
+      # Forbids referencing the named constants or anything under them. Use this
+      # when the boundary is a framework constant rather than a component.
+      #
+      #   models.cannot_reference_constants "ActionController", "ActionView"
+      #
+      # Rule id: +constants.forbid+.
       def cannot_reference_constants(*constants)
         add_rule(Rules::CannotReferenceConstantsRule.new(name, constants))
         self
       end
 
+      # Marks part of the component as its public API. References from outside
+      # must resolve to a public constant; everything else becomes private.
+      #
+      #   billing.public_api "packs/billing/app/public/**/*.rb"
+      #   billing.public_api constants: "Billing::Api"
+      #   billing.public_api namespace: "Billing::Public"
+      #
+      # +constants+ matches exact names, +namespace+ matches a name and its
+      # children. Code inside the component may still reach its own internals.
+      # Rule id: +dependencies.privacy+.
+      def public_api(*patterns, constants: nil, namespace: nil)
+        add_rule(Rules::PublicApiRule.new(name, files: patterns, constants: constants, namespaces: namespace))
+        self
+      end
+
+      # Forbids a concern from referencing the constants that include it. A
+      # concern that names its includer knows too much about who uses it, which
+      # couples the two and defeats the point of extracting the concern.
+      #
+      #   component :model_concerns, in: "app/models/concerns/**/*.rb"
+      #   model_concerns.cannot_reference_includers
+      #
+      # Rule id: +concerns.independence+.
+      def cannot_reference_includers
+        add_rule(Rules::ConcernIndependenceRule.new(name))
+        self
+      end
+
+      # Requires the component to hold no files. Use it to keep a directory
+      # empty, such as +app/services+ in a vanilla Rails app, with a reason
+      # shown in the diagnostic.
+      #
+      #   component(:services, in: "app/services/**/*.rb")
+      #     .must_be_empty(because: "behavior belongs on models")
+      #
+      # Rule id: +components.empty+.
       def must_be_empty(because: nil)
         add_rule(Rules::MustBeEmptyRule.new(name, because: because))
         self
       end
 
+      # Requires every class in the component to implement all the named
+      # instance methods. Methods inherited from resolvable superclasses or
+      # mixins count.
+      #
+      #   commands.must_implement :perform
+      #
+      # Rule id: +protocol.must_implement+.
       def must_implement(*methods)
         methods.each do |method_name|
           add_rule(Rules::MustImplementRule.new(name, method_name))
@@ -111,6 +318,12 @@ module ArchSpec
         self
       end
 
+      # Requires every class in the component to implement at least one of the
+      # named instance methods. Useful when a protocol allows either name.
+      #
+      #   commands.must_implement_one_of :perform, :call
+      #
+      # Rule id: +protocol.must_implement_one_of+.
       def must_implement_one_of(*methods)
         add_rule(Rules::MustImplementOneOfRule.new(name, methods))
         self

data/lib/archspec/evaluator.rb

@@ -4,14 +4,15 @@ module ArchSpec
   module Evaluator
     extend self
 
-    def evaluate(definition, graph, baseline: Baseline.empty)
+    def evaluate(definition, graph, todo: Todo.empty)
       (parser_diagnostics(graph) + definition.rules.flat_map { |rule| rule.evaluate(graph) })
         .reject { |diagnostic| graph.suppressed?(diagnostic) }
-        .reject { |diagnostic| baseline.include?(diagnostic) }
+        .reject { |diagnostic| todo.include?(diagnostic) }
         .sort_by do |diagnostic|
         [diagnostic.location.path, diagnostic.location.line, diagnostic.rule,
-         diagnostic.message]
+         diagnostic.message, diagnostic.evidence]
       end
+        .uniq { |diagnostic| [diagnostic.rule, diagnostic.message, diagnostic.location.path, diagnostic.location.line] }
     end
 
     private

data/lib/archspec/model.rb

@@ -71,7 +71,7 @@ module ArchSpec
     end
   end
 
-  Edge = ValueObject.define(:type, :from_path, :from_constant, :to, :location, :confidence)
+  Edge = ValueObject.define(:type, :from_path, :from_constant, :to, :location, :confidence, :receiver)
 
   class Component
     attr_reader :name, :files, :constants, :file_reasons, :constant_reasons
@@ -104,6 +104,8 @@ module ArchSpec
       extends
     ].freeze
 
+    RESOLVED_ROOTS = %w[Object BasicObject].freeze
+
     attr_reader :root, :files, :constants, :edges, :components
 
     def initialize(root)
@@ -136,8 +138,8 @@ module ArchSpec
       constant
     end
 
-    def add_edge(type:, from_path:, from_constant:, to:, location:, confidence: :high)
-      edges << Edge.new(type, from_path, from_constant, normalize_constant(to), location, confidence)
+    def add_edge(type:, from_path:, from_constant:, to:, location:, confidence: :high, receiver: nil)
+      edges << Edge.new(type, from_path, from_constant, normalize_constant(to), location, confidence, receiver)
     end
 
     def constants_named(name)
@@ -225,6 +227,39 @@ module ArchSpec
       candidates.find { |candidate| constants_named(candidate).any? } || normalized
     end
 
+    # Instance methods a constant responds to, walking resolvable superclasses
+    # and include/prepend mixins. Returns [methods, unresolved ancestor names];
+    # a non-empty second element means the answer is incomplete.
+    def effective_instance_methods(name, visited = Set.new)
+      normalized = normalize_constant(name)
+      return [Set.new, Set.new] if visited.include?(normalized)
+
+      visited.add(normalized)
+      return [Set.new, Set.new] if RESOLVED_ROOTS.include?(normalized)
+
+      nodes = constants_named(normalized)
+      return [Set.new, Set[normalized]] if nodes.empty?
+
+      methods = Set.new
+      unresolved = Set.new
+
+      nodes.each do |node|
+        methods.merge(node.instance_methods)
+
+        ancestors = node.mixins[:include].to_a + node.mixins[:prepend].to_a
+        ancestors << node.superclass if node.superclass
+
+        ancestors.each do |ancestor|
+          resolved_name = resolve_constant_reference(ancestor, node.name)
+          ancestor_methods, ancestor_unresolved = effective_instance_methods(resolved_name, visited)
+          methods.merge(ancestor_methods)
+          unresolved.merge(ancestor_unresolved)
+        end
+      end
+
+      [methods, unresolved]
+    end
+
     def component_dependency_pairs(only: nil)
       allowed_sources = Array(only).compact.map(&:to_sym).to_set
       pairs = Set.new

data/lib/archspec/presets.rb

@@ -1,9 +1,12 @@
 # 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

data/lib/archspec/rules/component_rules.rb

@@ -2,6 +2,8 @@
 
 module ArchSpec
   module Rules
+    # Backs ArchSpec::DSL::ComponentProxy#must_be_empty. Flags every file in a
+    # component that is meant to hold none.
     class MustBeEmptyRule
       attr_reader :source, :because
 

data/lib/archspec/rules/concern_rules.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Rules
+    # Backs ArchSpec::DSL::ComponentProxy#cannot_reference_includers. A concern
+    # is a module mixed into other classes; this flags a concern that names the
+    # very constant that includes it, which is a circular knowledge dependency.
+    class ConcernIndependenceRule
+      MIXIN_TYPES = %i[includes prepends extends].freeze
+
+      attr_reader :source
+
+      def initialize(source)
+        @source = source.to_sym
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def id
+        'concerns.independence'
+      end
+
+      def evaluate(graph)
+        component = graph.components[source]
+        return [] unless component
+
+        includers = includers_by_module(graph)
+
+        graph.dependency_edges.filter_map do |edge|
+          next unless edge.from_constant && component.constants.include?(edge.from_constant)
+
+          consumers = includers[edge.from_constant]
+          next if consumers.empty?
+
+          target = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          includer = consumers.find { |name| target == name || target.start_with?("#{name}::") }
+          next unless includer
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{edge.from_constant} must not reference its includer #{includer}",
+            location: edge.location,
+            evidence: "#{edge.from_constant} #{edge.type} #{target}"
+          )
+        end
+      end
+
+      private
+
+      # Maps each mixed-in module to the set of constants that mix it in.
+      def includers_by_module(graph)
+        map = Hash.new { |hash, key| hash[key] = Set.new }
+
+        graph.edges.each do |edge|
+          next unless MIXIN_TYPES.include?(edge.type) && edge.from_constant
+
+          mod = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          map[mod].add(edge.from_constant) unless mod == edge.from_constant
+        end
+
+        map
+      end
+    end
+  end
+end

data/lib/archspec/rules/cycle_rule.rb

@@ -2,6 +2,8 @@
 
 module ArchSpec
   module Rules
+    # 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

@@ -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_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/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