archspec 0.5.0 → 1.0.0

data/lib/archspec/cli.rb

@@ -16,15 +16,20 @@ module ArchSpec
     extend self
 
     CONFIG_FILE = 'Archspec.rb'
+    USAGE_ERROR_STATUS = 64
     TEMPLATE = <<~RUBY
       architecture :rails
     RUBY
 
+    class UsageError < Error; end
+
     def run(argv, output: $stdout, error: $stderr)
       argv = argv.dup
       command = argv.shift || 'check'
 
       case command
+      when 'help', '--help', '-h'
+        help(argv, output)
       when 'init'
         init(argv, output)
       when 'check'
@@ -32,47 +37,91 @@ module ArchSpec
       when 'explain'
         explain(argv, output)
       when 'version', '--version', '-v'
+        raise UsageError, "unexpected argument: #{argv.first}" if argv.any?
+
         output.puts ArchSpec::VERSION
         0
       else
-        error.puts "Unknown command: #{command}"
-        error.puts usage
-        64
+        raise UsageError, "unknown command: #{command}"
       end
+    rescue OptionParser::ParseError, UsageError => e
+      error.puts "archspec: error: #{e.message}"
+      error.puts usage(command)
+      USAGE_ERROR_STATUS
     rescue Error => e
-      error.puts e.message
+      error.puts "archspec: error: #{e.message}"
       1
     end
 
     private
 
+    def help(argv, output)
+      subject = argv.shift
+      raise UsageError, "unexpected argument: #{argv.first}" if argv.any?
+      if subject && !%w[init check explain version].include?(subject)
+        raise UsageError, "unknown command: #{subject}"
+      end
+
+      output.puts usage(subject)
+      0
+    end
+
     def init(argv, output)
-      force = argv.delete('--force')
+      options = { force: false, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = usage('init').strip
+        opts.on('--force', 'Overwrite an existing file') { options[:force] = true }
+        opts.on('-h', '--help', 'Show this help') { options[:help] = true }
+      end
+      parser.parse!(argv)
+
+      if options[:help]
+        output.puts parser
+        return 0
+      end
+
+      raise UsageError, "unexpected argument: #{argv[1]}" if argv.length > 1
+
       path = argv.shift || CONFIG_FILE
 
-      raise Error, "#{path} already exists. Use --force to overwrite it." if File.exist?(path) && !force
+      if File.exist?(path) && !options[:force]
+        raise Error, "#{path} already exists (use --force to overwrite)"
+      end
 
       File.write(path, TEMPLATE)
       output.puts "Created #{path}"
       0
+    rescue SystemCallError => e
+      raise Error, "could not create #{path}: #{e.message}"
     end
 
     def check(argv, output)
       options = {
         config: CONFIG_FILE,
         format: 'text',
-        update_todo: false
+        update_todo: false,
+        help: false
       }
 
       parser = OptionParser.new do |opts|
-        opts.on('--config PATH') { |value| options[:config] = value }
-        opts.on('--format FORMAT') { |value| options[:format] = value }
-        opts.on('--update-todo') { options[:update_todo] = true }
+        opts.banner = usage('check').strip
+        opts.on('--config PATH', 'Use a different architecture file') { |value| options[:config] = value }
+        opts.on('--format FORMAT', 'Output text or json') { |value| options[:format] = value }
+        opts.on('--update-todo', 'Replace the configured todo with current violations') do
+          options[:update_todo] = true
+        end
+        opts.on('-h', '--help', 'Show this help') { options[:help] = true }
       end
       parser.parse!(argv)
 
-      raise Error, 'Cannot combine --update-todo with path arguments.' if options[:update_todo] && argv.any?
+      if options[:help]
+        output.puts parser
+        return 0
+      end
+
+      raise Error, 'cannot combine --update-todo with path arguments' if options[:update_todo] && argv.any?
 
+      formatter = formatter_for(options[:format])
       definition, root = load_definition(options[:config])
       graph = Analyzer.analyze(definition, root: root)
       todo_path = todo_path_for(definition, root)
@@ -83,27 +132,38 @@ module ArchSpec
       if options[:update_todo]
         unless todo_path
           raise Error,
-                "No todo configured. Add `todo \"archspec_todo.yml\"` to #{options[:config]}."
+                "no todo configured; add `todo \"archspec_todo.yml\"` to #{options[:config]}"
         end
 
-        Todo.write(todo_path, diagnostics, root: root)
-        output.puts "Updated #{Pathname(todo_path).relative_path_from(Pathname(root))} with #{diagnostics.size} violations."
+        # Syntax errors are never an accepted baseline; they must be fixed.
+        accepted = diagnostics.reject { |diagnostic| diagnostic.rule == 'parser.syntax' }
+        Todo.write(todo_path, accepted, root: root)
+        label = accepted.size == 1 ? 'violation' : 'violations'
+        output.puts "Updated #{Pathname(todo_path).relative_path_from(Pathname(root))} with #{accepted.size} #{label}."
         return 0
       end
 
-      formatter_for(options[:format]).print(output, graph: graph, diagnostics: diagnostics)
+      formatter.print(output, graph: graph, diagnostics: diagnostics)
       diagnostics.empty? ? 0 : 1
     end
 
     def explain(argv, output)
-      options = { config: CONFIG_FILE }
+      options = { config: CONFIG_FILE, help: false }
       parser = OptionParser.new do |opts|
-        opts.on('--config PATH') { |value| options[:config] = value }
+        opts.banner = usage('explain').strip
+        opts.on('--config PATH', 'Use a different architecture file') { |value| options[:config] = value }
+        opts.on('-h', '--help', 'Show this help') { options[:help] = true }
       end
       parser.parse!(argv)
 
+      if options[:help]
+        output.puts parser
+        return 0
+      end
+
       subject = argv.shift
-      raise Error, 'Usage: archspec explain PATH_OR_CONSTANT' unless subject
+      raise UsageError, 'missing PATH_OR_CONSTANT' unless subject
+      raise UsageError, "unexpected argument: #{argv.first}" if argv.any?
 
       definition, root = load_definition(options[:config])
       graph = Analyzer.analyze(definition, root: root)
@@ -112,19 +172,25 @@ module ArchSpec
     end
 
     def load_definition(config_path)
-      raise Error, "Missing #{config_path}. Run `archspec init` first." unless File.exist?(config_path)
+      raise Error, "no #{config_path} found; run `archspec init` first" unless File.exist?(config_path)
 
-      ArchSpec.last_definition = nil
       absolute_config = File.expand_path(config_path)
-      config_dir = File.dirname(absolute_config)
       definition = Definition.new
-      definition.base_dir = config_dir
+      definition.base_dir = File.dirname(absolute_config)
       definition.extend(DSL::Context)
       definition.instance_eval(File.read(absolute_config), absolute_config)
-      definition = ArchSpec.last_definition || definition
-      definition.base_dir ||= config_dir
 
-      [definition, definition.absolute_root(config_dir)]
+      if definition.component_specs.empty? && definition.rules.empty?
+        raise Error, "#{config_path} declared no components or rules; the file's top level is already " \
+                     'the DSL, so do not wrap declarations in ArchSpec.define'
+      end
+
+      [definition, definition.absolute_root]
+    rescue Error
+      raise
+    rescue SyntaxError, LoadError, StandardError => e
+      detail = e.message.lines.first&.strip || e.class.name
+      raise Error, "could not load #{config_path}: #{detail}"
     end
 
     def scope_to_paths(diagnostics, paths, root)
@@ -151,18 +217,32 @@ module ArchSpec
       when 'json'
         Formatters::JSON
       else
-        raise Error, "Unknown format: #{name.inspect}"
+        raise UsageError, "unknown format: #{name.inspect}"
       end
     end
 
-    def usage
-      <<~TEXT
-        Usage:
-          archspec init [PATH] [--force]
-          archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]
-          archspec explain PATH_OR_CONSTANT [--config PATH]
-          archspec version
-      TEXT
+    def usage(command = nil)
+      case command.to_s
+      when 'init'
+        'Usage: archspec init [PATH] [--force]'
+      when 'check'
+        'Usage: archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]'
+      when 'explain'
+        'Usage: archspec explain PATH_OR_CONSTANT [--config PATH]'
+      when 'version'
+        'Usage: archspec version'
+      when ''
+        <<~TEXT
+          Usage:
+            archspec init [PATH] [--force]
+            archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]
+            archspec explain PATH_OR_CONSTANT [--config PATH]
+            archspec version
+            archspec help [COMMAND]
+        TEXT
+      else
+        usage
+      end
     end
   end
 end

data/lib/archspec/diagnostic.rb

@@ -36,6 +36,8 @@ module ArchSpec
         path: location.relative_path(root),
         line: location.line,
         column: location.column,
+        end_line: location.end_line,
+        end_column: location.end_column,
         evidence: evidence,
         confidence: confidence.to_s
       }

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.
     #
@@ -120,6 +130,7 @@ module ArchSpec
       #
       # Rule id: +dependencies.no_cycles+.
       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
 
@@ -162,6 +173,7 @@ module ArchSpec
       #
       # Rule id: +dependencies.allow+.
       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
@@ -173,6 +185,7 @@ module ArchSpec
       #
       # 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
@@ -185,6 +198,7 @@ module ArchSpec
       #
       # 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
@@ -288,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

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

@@ -3,79 +3,109 @@
 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.
+    # 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, graph, path)
+          explain_file(output, style, graph, path)
         else
-          explain_constant(output, graph, subject)
+          explain_constant(output, style, graph, subject)
         end
       end
 
-      def explain_file(output, graph, path)
+      def explain_file(output, style, 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
+        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, graph, subject)
+      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 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(', ')}"
+        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, assignments)
+      def print_component_reasons(output, style, assignments)
         if assignments.empty?
-          output.puts '  components: (none)'
+          output.puts "  #{style.note('components:')} (none)"
           return
         end
 
-        output.puts '  components:'
+        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, file)
+      def print_suppressions(output, style, file)
         return if file.suppressions.empty?
 
-        output.puts '  suppressions:'
-        file.suppressions.each do |suppression|
+        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 "    #{rule} on line #{line_range(suppression)}#{reason}"
+          output.puts "    #{style.faint(gutter)} #{rule}#{reason}"
         end
       end
 
-      def print_parse_errors(output, file)
+      def print_parse_errors(output, style, 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}"
+        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
 
@@ -83,7 +113,7 @@ module ArchSpec
         if suppression.end_line == Float::INFINITY
           "#{suppression.start_line}-EOF"
         elsif suppression.start_line == suppression.end_line
-          suppression.start_line
+          suppression.start_line.to_s
         else
           "#{suppression.start_line}-#{suppression.end_line}"
         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