archspec 0.4.0 → 1.0.0.rc1

data/lib/archspec/dsl.rb

@@ -8,6 +8,16 @@ module ArchSpec
   # An +Archspec.rb+ file is evaluated in this context, so every method here is
   # a top-level call in that file.
   module DSL
+    # Raises when any of +names+ is not a declared component. Shared by the
+    # top-level DSL and the component proxies.
+    def self.assert_known_components!(definition, names, for_rule:)
+      unknown = Array(names).flatten.compact.map(&:to_sym).reject { |name| definition.component?(name) }.uniq.sort
+      return if unknown.empty?
+
+      label = unknown.length == 1 ? 'component' : 'components'
+      raise Error, "#{for_rule} references unknown #{label}: #{unknown.join(', ')}"
+    end
+
     # The top-level DSL. Declare the project, its components, an architecture
     # preset, and global rules.
     #
@@ -56,16 +66,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 +97,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 +104,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 +111,29 @@ 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)
+        DSL.assert_known_components!(self, among, for_rule: 'no_cycles') if among
         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,40 +165,40 @@ 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)
+        DSL.assert_known_components!(definition, targets, for_rule: "#{name}.can_only_use")
         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
       #
       # Rule id: +dependencies.forbid+.
       def cannot_use(*targets)
+        DSL.assert_known_components!(definition, targets, for_rule: "#{name}.cannot_use")
         add_rule(Rules::ForbidDependenciesRule.new(name, targets))
         self
       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
       #
       # Rule id: +dependencies.consumers+.
       def can_only_be_used_by(*consumers)
+        DSL.assert_known_components!(definition, consumers, for_rule: "#{name}.can_only_be_used_by")
         add_rule(Rules::AllowedConsumersRule.new(name, consumers))
         self
       end
@@ -223,7 +212,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))
@@ -312,6 +302,8 @@ module ArchSpec
       #
       # Rule id: +protocol.must_implement+.
       def must_implement(*methods)
+        raise Error, 'must_implement requires at least one method' if methods.flatten.compact.empty?
+
         methods.each do |method_name|
           add_rule(Rules::MustImplementRule.new(name, method_name))
         end
@@ -329,6 +321,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/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  # Raised for configuration and usage errors, such as an unknown architecture
+  # name or a malformed rule option.
+  class Error < StandardError; end
+end

data/lib/archspec/evaluator.rb

@@ -5,14 +5,12 @@ module ArchSpec
     extend self
 
     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| todo.include?(diagnostic) }
-        .sort_by do |diagnostic|
-        [diagnostic.location.path, diagnostic.location.line, diagnostic.rule,
-         diagnostic.message, diagnostic.evidence]
-      end
-        .uniq { |diagnostic| [diagnostic.rule, diagnostic.message, diagnostic.location.path, diagnostic.location.line] }
+      diagnostics = parser_diagnostics(graph) + definition.rules.flat_map { |rule| rule.evaluate(graph) }
+
+      diagnostics
+        .reject { |diagnostic| graph.suppressed?(diagnostic) || todo.include?(diagnostic) }
+        .sort_by { |d| [d.location.path, d.location.line, d.rule, d.message, d.evidence] }
+        .uniq { |d| [d.rule, d.message, d.location.path, d.location.line] }
     end
 
     private

data/lib/archspec/formatters/explanation.rb

@@ -0,0 +1,123 @@
+# 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, in the same visual
+    # language as the check output. Raises ArchSpec::Error when the subject
+    # matches no file and no constant.
+    module Explanation
+      module_function
+
+      def print(output = $stdout, graph:, subject:)
+        style = Style.new(output)
+        path = File.expand_path(subject, graph.root)
+
+        if graph.files.key?(path)
+          explain_file(output, style, graph, path)
+        else
+          explain_constant(output, style, graph, subject)
+        end
+      end
+
+      def explain_file(output, style, graph, path)
+        file = graph.files.fetch(path)
+        output.puts style.bold(file.relative_path)
+        output.puts
+        output.puts "  #{style.note('defined constants:')} #{graph.constants_for_path(path).map(&:name).join(', ')}"
+        print_parse_errors(output, style, file)
+        print_component_reasons(output, style, graph.component_assignment_reasons_for_path(path))
+        print_suppressions(output, style, file)
+        print_facts(output, style, graph.edges.select { |edge| edge.from_path == path })
+      end
+
+      def explain_constant(output, style, graph, subject)
+        constants = graph.constants_named(subject)
+        raise Error, "no file or constant found for #{subject.inspect}" if constants.empty?
+
+        constants.each_with_index do |constant, index|
+          output.puts unless index.zero?
+          output.puts style.bold(constant.name)
+          output.puts
+          output.puts "  #{style.note('kind:')} #{constant.kind}"
+          output.puts "  #{style.note('file:')} #{constant.location.relative_path(graph.root)}:#{constant.location.line}"
+          print_component_reasons(
+            output, style,
+            graph.component_assignment_reasons_for_constant(constant.name, path: constant.path)
+          )
+          output.puts "  #{style.note('superclass:')} #{constant.superclass || '(none)'}"
+          output.puts "  #{style.note('instance methods:')} #{constant.instance_methods.to_a.sort.join(', ')}"
+          output.puts "  #{style.note('class methods:')} #{constant.class_methods.to_a.sort.join(', ')}"
+        end
+      end
+
+      def print_component_reasons(output, style, assignments)
+        if assignments.empty?
+          output.puts "  #{style.note('components:')} (none)"
+          return
+        end
+
+        output.puts "  #{style.note('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, style, file)
+        return if file.suppressions.empty?
+
+        output.puts "  #{style.note('suppressions:')}"
+        in_gutters(file.suppressions.map { |suppression| line_range(suppression) }) do |gutter, index|
+          suppression = file.suppressions[index]
+          rule = suppression.rule || '*'
+          reason = suppression.reason ? " -- #{suppression.reason}" : ''
+          output.puts "    #{style.faint(gutter)} #{rule}#{reason}"
+        end
+      end
+
+      def print_parse_errors(output, style, file)
+        return if file.parse_errors.empty?
+
+        output.puts "  #{style.note('parse errors:')}"
+        locations = file.parse_errors.map { |error| "#{error.location.line}:#{error.location.column}" }
+        in_gutters(locations) do |gutter, index|
+          output.puts "    #{style.faint(gutter)} #{file.parse_errors[index].message}"
+        end
+      end
+
+      def print_facts(output, style, facts)
+        if facts.empty?
+          output.puts "  #{style.note('outgoing facts:')} (none)"
+          return
+        end
+
+        output.puts "  #{style.note('outgoing facts:')}"
+        locations = facts.map { |edge| "#{edge.location.line}:#{edge.location.column}" }
+        in_gutters(locations) do |gutter, index|
+          edge = facts[index]
+          output.puts "    #{style.faint(gutter)} #{edge.verb} #{edge.to}"
+        end
+      end
+
+      # Yields each label right-justified to the widest one, with the frame
+      # gutter bar appended, so columns line up like the check output.
+      def in_gutters(labels)
+        width = labels.map(&:length).max
+
+        labels.each_with_index do |label, index|
+          yield "#{label.rjust(width)} │", index
+        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.to_s
+        else
+          "#{suppression.start_line}-#{suppression.end_line}"
+        end
+      end
+    end
+  end
+end

data/lib/archspec/formatters/style.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Formatters
+    # ANSI styling for terminal output, shared by the formatters. Enabled only
+    # when the output is a TTY and NO_COLOR is unset.
+    class Style
+      def initialize(output)
+        @enabled = output.respond_to?(:tty?) && output.tty? && ENV['NO_COLOR'].to_s.empty?
+      end
+
+      def bold(text)
+        paint(text, '1')
+      end
+
+      def severity(text)
+        paint(text, '1;31')
+      end
+
+      def marker(text)
+        paint(text, '1;31')
+      end
+
+      def note(text)
+        paint(text, '1;36')
+      end
+
+      def faint(text)
+        paint(text, '2')
+      end
+
+      private
+
+      def paint(text, code)
+        @enabled ? "\e[#{code}m#{text}\e[0m" : text
+      end
+    end
+  end
+end

data/lib/archspec/formatters/text.rb

@@ -2,26 +2,110 @@
 
 module ArchSpec
   module Formatters
+    # Prints diagnostics the way clang and herb do: a severity header with the
+    # rule id, the location, a code frame with the offending span underlined,
+    # and the evidence as a note.
+    #
+    #   [error] models must not depend on controllers [dependencies.forbid]
+    #
+    #   app/models/user.rb:3:3
+    #
+    #       2 │ class User
+    #     → 3 │   UsersController
+    #         │   ^~~~~~~~~~~~~~~
+    #       4 │ end
+    #
+    #     note: User references UsersController
+    #
+    # Output to a terminal is colored; a non-TTY or a NO_COLOR environment
+    # disables the colors.
     module Text
+      CONTEXT_LINES = 1
+
       module_function
 
       def print(output = $stdout, graph:, diagnostics:)
         if diagnostics.empty?
-          output.puts "ArchSpec passed: #{graph.files.size} files, #{graph.constants.size} constants, #{graph.edges.size} facts checked."
+          output.puts "ArchSpec passed: #{graph.files.size} files, #{graph.constants.size} constants, " \
+                      "#{graph.edges.size} facts checked."
           return
         end
 
-        output.puts "#{diagnostics.size} architecture #{diagnostics.size == 1 ? 'violation' : 'violations'}"
-        output.puts
+        style = Style.new(output)
+        sources = Hash.new { |hash, path| hash[path] = read_lines(path) }
 
         diagnostics.each do |diagnostic|
-          output.puts "[#{diagnostic.rule}] #{diagnostic.location.relative_path(graph.root)}:#{diagnostic.location.line}:#{diagnostic.location.column}"
-          output.puts "  #{diagnostic.message}"
-          output.puts "  evidence: #{diagnostic.evidence}"
-          output.puts "  confidence: #{diagnostic.confidence}"
-          output.puts "  id: #{diagnostic.fingerprint(root: graph.root)}"
+          print_diagnostic(output, style, graph, diagnostic, sources)
+        end
+
+        label = diagnostics.size == 1 ? 'architecture violation' : 'architecture violations'
+        output.puts style.bold("#{diagnostics.size} #{label} found.")
+      end
+
+      def print_diagnostic(output, style, graph, diagnostic, sources)
+        location = diagnostic.location
+        relative = location.relative_path(graph.root)
+
+        output.puts "#{style.severity('[error]')} #{style.bold(diagnostic.message)} #{style.faint("[#{diagnostic.rule}]")}"
+        output.puts
+        output.puts "#{relative}:#{location.line}:#{location.column}"
+        print_frame(output, style, location, sources[location.path])
+
+        if (note = note_for(diagnostic, relative))
           output.puts
+          output.puts "  #{style.note('note:')} #{note}"
         end
+        output.puts
+      end
+
+      def print_frame(output, style, location, lines)
+        target = lines[location.line - 1]
+        return unless target
+
+        output.puts
+        first = [location.line - CONTEXT_LINES, 1].max
+        last = [location.line + CONTEXT_LINES, lines.size].min
+        width = last.to_s.length
+
+        (first..last).each do |number|
+          text = lines[number - 1]
+          if number == location.line
+            output.puts "  #{style.marker('→')} #{style.faint("#{number.to_s.rjust(width)} │")} #{text}"
+            output.puts "    #{style.faint("#{' ' * width} │")} #{style.marker(underline(location, target))}"
+          else
+            output.puts "    #{style.faint("#{number.to_s.rjust(width)} │")} #{text}"
+          end
+        end
+      end
+
+      # The evidence as a note, or nil when it would only repeat the location
+      # shown above it, as parse-error evidence does.
+      def note_for(diagnostic, relative)
+        note = diagnostic.evidence.to_s
+        return if note.empty? || note == relative
+
+        note = "#{note} (confidence: #{diagnostic.confidence})" unless diagnostic.confidence == :high
+        note
+      end
+
+      def underline(location, text)
+        span =
+          if location.end_line == location.line
+            location.end_column - location.column
+          else
+            text.length - location.column + 1
+          end
+        span = span.clamp(1, [text.length - location.column + 1, 1].max)
+
+        "#{' ' * (location.column - 1)}^#{'~' * (span - 1)}"
+      end
+
+      def read_lines(path)
+        return [] unless File.file?(path)
+
+        File.readlines(path, chomp: true).map { |line| line.scrub.tr("\t", ' ') }
+      rescue SystemCallError
+        []
       end
     end
   end