archspec 0.3.0 → 0.5.0

data/lib/archspec/architectures.rb

@@ -1,6 +1,45 @@
 # frozen_string_literal: true
 
 module ArchSpec
+  # Bundled architecture presets. Each applies a set of components and rules in
+  # one call, invoked from the DSL through
+  # ArchSpec::DSL::Context#architecture:
+  #
+  #   architecture :rails
+  #   architecture :layered, layers: { ... }
+  #
+  # Every preset accepts overrides for its directories, so you can keep the
+  # shape while pointing at your own paths. The presets are:
+  #
+  # - +:rails+ (aliases +:rails_mvc+, +:rails_way+): conventional MVC that keeps
+  #   controller APIs out of models and services. Options +components:+,
+  #   +controller_api:+, +share_helpers:+.
+  # - +:rails_strict+: +:rails+ plus a cycle check and a concern independence
+  #   check. Adds option +concerns:+.
+  # - +:vanilla_rails+: +:rails+ plus empty-directory rules for the 37signals
+  #   style (forbidding +app/services+, +app/forms+, +app/policies+, and more)
+  #   and the concern independence check. Options +components:+, +empty:+,
+  #   +controller_api:+, +share_helpers:+, +concerns:+.
+  # - +:layered+ (alias +:rails_layered+): ordered layers that may only depend
+  #   inward, with a cycle check. Option +layers:+ (order matters).
+  # - +:hexagonal+ (alias +:rails_hexagonal+): ports and adapters, keeping the
+  #   domain away from adapters. Options +application:+, +domain:+, +ports:+,
+  #   +adapters:+.
+  # - +:clean+ (alias +:rails_clean+): clean architecture layers. Options
+  #   +frameworks:+, +interface_adapters:+, +use_cases:+, +entities:+.
+  # - +:modular_monolith+ (alias +:bounded_contexts+): named packages with
+  #   per-package allowlists and optional public APIs. Options +components:+
+  #   (required), +allow:+, +public:+.
+  # - +:cqrs+ (alias +:rails_cqrs+): separates commands from queries and keeps
+  #   writes out of queries. Options +commands:+, +queries:+, +read_models:+,
+  #   +mutating_methods:+.
+  # - +:event_driven+ (alias +:rails_event_driven+): events, publishers, and
+  #   subscribers. Options +events:+, +publishers:+, +subscribers:+.
+  # - +:ruby_conventions+: generic Ruby naming idioms (no +get_+/+set_+, no +is_+
+  #   prefix), applied project-wide. Adds no components, so it composes with any
+  #   other architecture. No options.
+  #
+  # See the guides at https://archspecrb.dev/architectures/ for each in depth.
   module Architectures
     extend self
 
@@ -54,6 +93,8 @@ module ArchSpec
       view_components: ['app/components/**/*.rb', 'use helpers and ERB partials']
     }.freeze
 
+    DEFAULT_CONCERNS = 'app/**/concerns/**/*.rb'
+
     CONTROLLER_METHODS = %i[render redirect_to params session cookies flash].freeze
     MUTATING_METHODS = %i[
       create create!
@@ -65,17 +106,34 @@ module ArchSpec
       upsert upsert!
     ].freeze
 
+    # Applies the named preset to +dsl+, forwarding +options+ to it. Raises
+    # ArchSpec::Error for an unknown name. Called by
+    # ArchSpec::DSL::Context#architecture, so you rarely call it directly.
     def apply(name, dsl, **options)
       case name.to_sym
       when :rails, :rails_mvc, :rails_way
-        rails_mvc(dsl, components: options.fetch(:components, DEFAULT_RAILS_MVC))
+        rails_mvc(
+          dsl,
+          components: options.fetch(:components, DEFAULT_RAILS_MVC),
+          controller_api: options.fetch(:controller_api, CONTROLLER_METHODS),
+          share_helpers: options.fetch(:share_helpers, false)
+        )
       when :rails_strict
-        rails_strict(dsl, components: options.fetch(:components, DEFAULT_RAILS_MVC))
+        rails_strict(
+          dsl,
+          components: options.fetch(:components, DEFAULT_RAILS_MVC),
+          controller_api: options.fetch(:controller_api, CONTROLLER_METHODS),
+          share_helpers: options.fetch(:share_helpers, false),
+          concerns: options.fetch(:concerns, DEFAULT_CONCERNS)
+        )
       when :vanilla_rails
         vanilla_rails(
           dsl,
           components: options.fetch(:components, DEFAULT_RAILS_MVC),
-          empty: options.fetch(:empty, VANILLA_RAILS_EMPTY)
+          empty: options.fetch(:empty, VANILLA_RAILS_EMPTY),
+          controller_api: options.fetch(:controller_api, CONTROLLER_METHODS),
+          share_helpers: options.fetch(:share_helpers, false),
+          concerns: options.fetch(:concerns, DEFAULT_CONCERNS)
         )
       when :layered, :rails_layered
         layered(dsl, layers: options.fetch(:layers, DEFAULT_LAYERED))
@@ -84,40 +142,54 @@ module ArchSpec
       when :clean, :rails_clean
         clean(dsl, **with_defaults(DEFAULT_CLEAN, options))
       when :modular_monolith, :bounded_contexts
-        modular_monolith(dsl, components: options.fetch(:components), allow: options.fetch(:allow, {}))
+        modular_monolith(
+          dsl,
+          components: options.fetch(:components),
+          allow: options.fetch(:allow, {}),
+          public: options.fetch(:public, {})
+        )
       when :cqrs, :rails_cqrs
         cqrs(dsl, **with_defaults(DEFAULT_CQRS, options))
       when :event_driven, :rails_event_driven
         event_driven(dsl, **with_defaults(DEFAULT_EVENT_DRIVEN, options))
+      when :ruby_conventions
+        ruby_conventions(dsl)
       else
         raise Error, "Unknown ArchSpec architecture: #{name.inspect}"
       end
     end
 
-    def rails_mvc(dsl, components:)
+    def rails_mvc(dsl, components:, controller_api: CONTROLLER_METHODS, share_helpers: false)
       components = normalize_map(components)
       define_components(dsl, components)
 
-      proxy_for(dsl, :controllers).can_use(*components.keys & %i[models services helpers mailers jobs])
-      proxy_for(dsl, :models).cannot_use(*components.keys & %i[controllers helpers])
-      proxy_for(dsl, :services).cannot_use(*components.keys & %i[controllers helpers])
-      proxy_for(dsl, :models).cannot_call(*CONTROLLER_METHODS)
-      proxy_for(dsl, :services).cannot_call(*CONTROLLER_METHODS)
+      forbidden = share_helpers ? %i[controllers] : %i[controllers helpers]
+      proxy_for(dsl, :controllers).can_only_use(*components.keys & %i[models services helpers mailers jobs])
+      proxy_for(dsl, :models).cannot_use(*components.keys & forbidden)
+      proxy_for(dsl, :services).cannot_use(*components.keys & forbidden)
+
+      return if controller_api.empty?
+
+      proxy_for(dsl, :models).cannot_call(*controller_api, receiver: :none)
+      proxy_for(dsl, :services).cannot_call(*controller_api, receiver: :none)
     end
 
-    def rails_strict(dsl, components:)
+    def rails_strict(dsl, components:, controller_api: CONTROLLER_METHODS, share_helpers: false, concerns: DEFAULT_CONCERNS)
       components = normalize_map(components)
-      rails_mvc(dsl, components: components)
-      dsl.verify_zeitwerk_names!
-      dsl.no_cycles!(among: components.keys)
+      rails_mvc(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
+      dsl.no_cycles(among: components.keys)
+      independent_concerns(dsl, concerns)
     end
 
-    def vanilla_rails(dsl, components:, empty:)
-      rails_mvc(dsl, components: components)
+    def vanilla_rails(dsl, components:, empty:, controller_api: CONTROLLER_METHODS, share_helpers: false,
+                      concerns: DEFAULT_CONCERNS)
+      rails_mvc(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
 
       empty.each do |name, (pattern, reason)|
         dsl.component(name, in: pattern).must_be_empty(because: reason)
       end
+
+      independent_concerns(dsl, concerns)
     end
 
     def layered(dsl, layers:)
@@ -127,10 +199,10 @@ module ArchSpec
 
       names.each_with_index do |name, index|
         allowed = names[(index + 1)..] || []
-        proxy_for(dsl, name).can_use(*allowed)
+        proxy_for(dsl, name).can_only_use(*allowed)
       end
 
-      dsl.no_cycles!(among: names)
+      dsl.no_cycles(among: names)
     end
 
     def hexagonal(dsl, application:, domain:, ports:, adapters:)
@@ -142,11 +214,11 @@ module ArchSpec
       )
       define_components(dsl, roles)
 
-      proxy_for(dsl, :application).can_use :domain, :ports
+      proxy_for(dsl, :application).can_only_use :domain, :ports
       proxy_for(dsl, :domain).cannot_use :adapters
       proxy_for(dsl, :ports).cannot_use :adapters
-      proxy_for(dsl, :adapters).can_use :application, :domain, :ports
-      dsl.no_cycles!(among: roles.keys)
+      proxy_for(dsl, :adapters).can_only_use :application, :domain, :ports
+      dsl.no_cycles(among: roles.keys)
     end
 
     def clean(dsl, frameworks:, interface_adapters:, use_cases:, entities:)
@@ -161,16 +233,19 @@ module ArchSpec
       )
     end
 
-    def modular_monolith(dsl, components:, allow: {})
+    def modular_monolith(dsl, components:, allow: {}, public: {})
       components = normalize_map(components)
       define_components(dsl, components)
 
       components.each_key do |name|
         allowed = Array(allow[name] || allow[name.to_s])
-        proxy_for(dsl, name).can_use(*allowed)
+        proxy_for(dsl, name).can_only_use(*allowed)
+
+        patterns = Array(public[name] || public[name.to_s])
+        proxy_for(dsl, name).public_api(*patterns) if patterns.any?
       end
 
-      dsl.no_cycles!(among: components.keys)
+      dsl.no_cycles(among: components.keys)
     end
 
     def cqrs(dsl, commands:, queries:, read_models: nil, mutating_methods: MUTATING_METHODS)
@@ -181,7 +256,7 @@ module ArchSpec
       proxy_for(dsl, :commands).cannot_use :queries
       proxy_for(dsl, :queries).cannot_use :commands
       proxy_for(dsl, :queries).cannot_call(*mutating_methods)
-      dsl.no_cycles!(among: components.keys)
+      dsl.no_cycles(among: components.keys)
     end
 
     def event_driven(dsl, events:, publishers:, subscribers:)
@@ -189,13 +264,36 @@ module ArchSpec
       define_components(dsl, roles)
 
       proxy_for(dsl, :events).cannot_use :publishers, :subscribers
-      proxy_for(dsl, :publishers).can_use :events
-      proxy_for(dsl, :subscribers).can_use :events
-      dsl.no_cycles!(among: roles.keys)
+      proxy_for(dsl, :publishers).can_only_use :events
+      proxy_for(dsl, :subscribers).can_only_use :events
+      dsl.no_cycles(among: roles.keys)
+    end
+
+    # Applies the generic Ruby naming idioms project-wide: no +get_+/+set_+
+    # accessors and no +is_+ predicate prefix. Adds no components, so it composes
+    # with any other architecture. Project-specific conventions (the +with_x+ /
+    # +without_x+ pairing, the +supports_*?+ ban) stay opt-in through the
+    # +method_names.matching(...)+ primitives.
+    def ruby_conventions(dsl)
+      %i[instance class].each do |scope|
+        forbid_name(dsl, /\A(get|set)_/, 'use attr_ readers and writers or plain names, not get_/set_', scope: scope)
+        forbid_name(dsl, /\Ais_/, 'name predicates with a trailing ? and no is_ prefix (has_ is fine)', scope: scope)
+      end
     end
 
     private
 
+    def forbid_name(dsl, regex, reason, scope:)
+      dsl.rule(
+        Rules::NamingRule.new(
+          source: nil,
+          selector: Rules::Naming::NameSelector.new(regex),
+          constraint: Rules::Naming::Forbidden.new(because: reason),
+          scope: scope
+        )
+      )
+    end
+
     def with_defaults(defaults, options)
       defaults.merge(options)
     end
@@ -226,5 +324,13 @@ module ArchSpec
     def proxy_for(dsl, name)
       DSL::ComponentProxy.new(dsl, name)
     end
+
+    def independent_concerns(dsl, pattern)
+      return unless pattern
+
+      dsl.component(:concerns, in: pattern).cannot_reference_includers
+      # Controllers carry an allowlist, so let them include concerns too.
+      proxy_for(dsl, :controllers).can_only_use(:concerns)
+    end
   end
 end

data/lib/archspec/cli.rb

@@ -3,6 +3,15 @@
 require 'optparse'
 
 module ArchSpec
+  # The <tt>archspec</tt> command line. Backs the +exe/archspec+ executable and
+  # dispatches the +init+, +check+, +explain+, and +version+ subcommands.
+  #
+  #   archspec init
+  #   archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]
+  #   archspec explain PATH_OR_CONSTANT
+  #
+  # #run returns the process exit status: 0 when clean, 1 when violations are
+  # found.
   module CLI
     extend self
 
@@ -52,30 +61,33 @@ module ArchSpec
       options = {
         config: CONFIG_FILE,
         format: 'text',
-        update_baseline: false
+        update_todo: 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-baseline') { options[:update_baseline] = true }
+        opts.on('--update-todo') { options[:update_todo] = true }
       end
       parser.parse!(argv)
 
+      raise Error, 'Cannot combine --update-todo with path arguments.' if options[:update_todo] && argv.any?
+
       definition, root = load_definition(options[:config])
       graph = Analyzer.analyze(definition, root: root)
-      baseline_path = baseline_path_for(definition, root)
-      baseline = options[:update_baseline] ? Baseline.empty(root: root) : Baseline.load(baseline_path, root: root)
-      diagnostics = Evaluator.evaluate(definition, graph, baseline: baseline)
+      todo_path = todo_path_for(definition, root)
+      todo = options[:update_todo] ? Todo.empty(root: root) : Todo.load(todo_path, root: root)
+      diagnostics = Evaluator.evaluate(definition, graph, todo: todo)
+      diagnostics = scope_to_paths(diagnostics, argv, root)
 
-      if options[:update_baseline]
-        unless baseline_path
+      if options[:update_todo]
+        unless todo_path
           raise Error,
-                "No baseline configured. Add `baseline \".archspec_todo.yml\"` to #{options[:config]}."
+                "No todo configured. Add `todo \"archspec_todo.yml\"` to #{options[:config]}."
         end
 
-        Baseline.write(baseline_path, diagnostics, root: root)
-        output.puts "Updated #{Pathname(baseline_path).relative_path_from(Pathname(root))} with #{diagnostics.size} violations."
+        Todo.write(todo_path, diagnostics, root: root)
+        output.puts "Updated #{Pathname(todo_path).relative_path_from(Pathname(root))} with #{diagnostics.size} violations."
         return 0
       end
 
@@ -95,7 +107,7 @@ module ArchSpec
 
       definition, root = load_definition(options[:config])
       graph = Analyzer.analyze(definition, root: root)
-      explain_subject(output, graph, subject)
+      Formatters::Explanation.print(output, graph: graph, subject: subject)
       0
     end
 
@@ -104,18 +116,32 @@ module ArchSpec
 
       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.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)]
+    end
 
-      [definition, definition.absolute_root(File.dirname(absolute_config))]
+    def scope_to_paths(diagnostics, paths, root)
+      return diagnostics if paths.empty?
+
+      expanded = paths.map { |path| File.expand_path(path, root) }
+      diagnostics.select do |diagnostic|
+        expanded.any? do |path|
+          diagnostic.location.path == path || diagnostic.location.path.start_with?("#{path}/")
+        end
+      end
     end
 
-    def baseline_path_for(definition, root)
-      return unless definition.baseline_path
+    def todo_path_for(definition, root)
+      return unless definition.todo_path
 
-      File.expand_path(definition.baseline_path, root)
+      File.expand_path(definition.todo_path, root)
     end
 
     def formatter_for(name)
@@ -129,83 +155,11 @@ module ArchSpec
       end
     end
 
-    def explain_subject(output, graph, subject)
-      path = File.expand_path(subject, graph.root)
-
-      if graph.files.key?(path)
-        file = graph.files.fetch(path)
-        output.puts file.relative_path
-        output.puts "  expected constant: #{file.expected_constant || '(none)'}"
-        output.puts "  defined constants: #{graph.constants_for_path(path).map(&:name).join(', ')}"
-        output_parse_errors(output, file)
-        output_component_reasons(output, graph.component_assignment_reasons_for_path(path))
-        output_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
-      else
-        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}"
-          output_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
-    end
-
-    def output_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 output_suppressions(output, file)
-      return if file.suppressions.empty?
-
-      output.puts '  suppressions:'
-      file.suppressions.each do |suppression|
-        line_range =
-          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
-        rule = suppression.rule || '*'
-        reason = suppression.reason ? " -- #{suppression.reason}" : ''
-        output.puts "    #{rule} on line #{line_range}#{reason}"
-      end
-    end
-
-    def output_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 usage
       <<~TEXT
         Usage:
           archspec init [PATH] [--force]
-          archspec check [--config PATH] [--format text|json] [--update-baseline]
+          archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]
           archspec explain PATH_OR_CONSTANT [--config PATH]
           archspec version
       TEXT

data/lib/archspec/component_spec.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module ArchSpec
+  # How a component selects its members: by file glob, by namespace, or by
+  # explicit constant name. Created by ArchSpec::DSL::Context#component. The
+  # analyzer uses it to assign files and constants to the component.
   class ComponentSpec
     attr_reader :name, :file_patterns, :namespaces, :constants
 

data/lib/archspec/definition.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module ArchSpec
+  # The result of evaluating an +Archspec.rb+ file: the project settings,
+  # declared components, and rules. ArchSpec::DSL::Context is mixed into an
+  # instance to provide the DSL, and the analyzer and evaluator read it to run
+  # the checks. Build one with ArchSpec.define.
   class Definition
     DEFAULT_SOURCE_PATTERNS = [
       'app/**/*.rb',
@@ -17,13 +21,14 @@ module ArchSpec
       'vendor/**/*'
     ].freeze
 
-    attr_accessor :name, :root_path, :baseline_path
+    attr_accessor :name, :root_path, :todo_path, :base_dir
     attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules
 
     def initialize(name = nil)
       @name = name
       @root_path = '.'
-      @baseline_path = nil
+      @todo_path = nil
+      @base_dir = nil
       @source_patterns = []
       @ignore_patterns = DEFAULT_IGNORE_PATTERNS.dup
       @component_specs = {}
@@ -54,8 +59,11 @@ module ArchSpec
       rules << rule
     end
 
-    def absolute_root(base_dir = Dir.pwd)
-      File.expand_path(root_path, base_dir)
+    # The directory file patterns resolve against: root_path expanded from the
+    # directory the Archspec.rb was loaded from (base_dir), or the working
+    # directory when built without a file.
+    def absolute_root(base = base_dir || Dir.pwd)
+      File.expand_path(root_path, base)
     end
 
     def analysis_patterns

data/lib/archspec/diagnostic.rb

@@ -3,6 +3,10 @@
 require 'digest'
 
 module ArchSpec
+  # One reported violation: the rule id, a message, the source location, the
+  # evidence ArchSpec found, and a confidence. Formatters and the todo file read
+  # these. Its #fingerprint is the stable id used to match todo entries and
+  # suppress specific findings.
   class Diagnostic
     attr_reader :rule, :message, :location, :evidence, :confidence
 
@@ -14,11 +18,13 @@ module ArchSpec
       @confidence = confidence
     end
 
+    # Line numbers stay out of the fingerprint so todo entries survive edits
+    # that only shift code around.
     def fingerprint(root: nil)
       path = root ? location.relative_path(root) : location.path
 
       Digest::SHA256.hexdigest(
-        [rule, message, path, location.line, evidence].join("\0")
+        [rule, message, path, evidence].join("\0")
       )[0, 24]
     end