archspec 0.3.0 → 0.5.0

data/lib/archspec/dsl.rb

@@ -1,26 +1,92 @@
 # 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
+
+      # 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.
       def component(name, in: nil, namespace: nil, constants: nil)
         add_component(
           ComponentSpec.new(name, files: binding.local_variable_get(:in), namespace: namespace, constants: constants)
@@ -28,21 +94,38 @@ module ArchSpec
         ComponentProxy.new(self, name)
       end
 
-      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: { ... }
+      #
+      # +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
 
-      def no_cycles!(among: nil)
-        add_rule(Rules::NoCyclesRule.new(among: among))
-      end
+      alias preset architecture
 
-      def verify_zeitwerk_names!
-        add_rule(Rules::ZeitwerkNamingRule.new)
+      # 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
 
+      # 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 +141,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,44 +154,139 @@ module ArchSpec
         @name = name.to_sym
       end
 
-      def can_use(*targets)
+      # 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_only_use :models, :services
+      #
+      # Rule id: +dependencies.allow+.
+      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_only_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_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
+      #
+      # 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_*+, 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))
+        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,11 +294,32 @@ 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
       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/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/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,22 +55,31 @@ 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)
+  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 +112,8 @@ module ArchSpec
       extends
     ].freeze
 
+    RESOLVED_ROOTS = %w[Object BasicObject].freeze
+
     attr_reader :root, :files, :constants, :edges, :components
 
     def initialize(root)
@@ -115,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
       )
@@ -136,8 +145,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)
@@ -155,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 = {}
 
@@ -225,6 +240,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/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