archspec 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 583efdae4f510098da5807cb0d7f509892851f5f26766e705dd6354c1e6b1748
-  data.tar.gz: 5523396837663f507b4b474bcc1fd2a803f59f60910047b1dc9e910b1b46fde5
+  metadata.gz: 25ea714cd768976e860df4f0dbaa9ff477e381096f95b98787a0a645fc0cd776
+  data.tar.gz: 527621e2bb18514433cf26ede594f2cafa2699d0d95e2d3fa4d9e8b9e4aac354
 SHA512:
-  metadata.gz: 4761e204b83d63afcaa16c823aa47ba6c39653990d30c30dadd94e0698ffc0dc8566cb0740125c9948c630ab983183b5907828691a55d36a66f314df5f35ea8b
-  data.tar.gz: d5e8219c53e25cf060e78d74f8e23c75d7fc6204451ee1faf4a7f1ecac8caf53ce02b27d13bb194ca83810d7874e720385ec9daa31508d6840f9bb068c00ba88
+  metadata.gz: f9c83e97692a44bbf72391593e695bc4c8a7859d148508f4cb8cf490a55e51a8de98d0df8ab0d37bf8bf13fcdb3e4707f9325850a39b9a33ea678a0d0aa7f3b2
+  data.tar.gz: ec19d8b85144cee92cd7bd2c968d848aef39feccdda87b56849dab7ac706543fec8041bee524ab0c5532193b423442f6ef3eec00d6d52f6301ec3e960b5cf1b8

data/README.md

@@ -67,7 +67,7 @@ Keep a hexagonal core away from adapters:
 architecture :hexagonal
 ```
 
-Check a modular monolith:
+Check a modular monolith, and make packs go through a public API:
 
 ```ruby
 architecture :modular_monolith,
@@ -79,6 +79,9 @@ architecture :modular_monolith,
   allow: {
     billing: %i[shared],
     catalog: %i[shared]
+  },
+  public: {
+    billing: "packs/billing/app/public/**/*.rb"
   }
 ```
 
@@ -106,7 +109,9 @@ architecture :cqrs,
 
 ## What It Checks
 
-- **Dependencies:** allowed and forbidden references between components
+- **Dependencies:** allowed and forbidden references between components, in both directions
+- **Privacy:** other components must go through a component's public API
+- **Concerns:** a concern must not depend on the classes that include it
 - **Layers:** dependency direction and cycles
 - **Rails:** controller APIs kept out of models and services
 - **Architectures:** Rails, vanilla Rails, layered, hexagonal, clean, modular monolith, CQRS, and event-driven bundles
@@ -150,7 +155,7 @@ bundle exec archspec check
 bundle exec archspec init
 bundle exec archspec check
 bundle exec archspec check --format json
-bundle exec archspec check --update-baseline
+bundle exec archspec check --update-todo
 bundle exec archspec explain app/models/user.rb
 ```
 
@@ -161,12 +166,15 @@ facts ArchSpec found.
 
 Generated code should pass the same architecture checks as hand-written code.
 
-After an AI-assisted change:
+After an AI-assisted change, check the whole project, or just the files that changed:
 
 ```sh
 bundle exec archspec check
+bundle exec archspec check app/models/user.rb app/services
 ```
 
+Passing paths still analyzes the project so dependencies resolve, but reports only violations in those paths. This keeps the loop tight after each edit.
+
 If it fails, read the evidence before changing the spec:
 
 ```text
@@ -179,16 +187,17 @@ If it fails, read the evidence before changing the spec:
 Most failures should be fixed in the generated code. Update the spec only when
 the architecture decision itself has changed.
 
-## Baselines and Suppressions
+## Todo and Suppressions
 
-Use a baseline when adopting ArchSpec in an existing app:
+Use a todo file when adopting ArchSpec in an existing app. It records the current
+violations so they stop failing the build, leaving a list to burn down:
 
 ```ruby
-baseline ".archspec_todo.yml"
+todo "archspec_todo.yml"
 ```
 
 ```sh
-bundle exec archspec check --update-baseline
+bundle exec archspec check --update-todo
 ```
 
 Use local suppressions for deliberate exceptions:
@@ -210,6 +219,12 @@ This repository checks its own architecture:
 bundle exec rake architecture
 ```
 
+It also runs against pinned checkouts of large real-world Rails apps to catch crashes and false positives before they ship:
+
+```sh
+bundle exec rake torture
+```
+
 ## License
 
 Released under the MIT License.

data/lib/archspec/analyzer.rb

@@ -15,7 +15,7 @@ module ArchSpec
         result = Prism.parse_file(path)
         graph.add_file(
           path: path,
-          expected_constant: expected_constant_for(path, root),
+          expected_constant: expected_constant_for(path, root, definition.inflections),
           parse_errors: parse_errors_for(path, result.errors),
           suppressions: suppressions_for(result.comments)
         )
@@ -49,7 +49,7 @@ module ArchSpec
       end.select { |path| File.file?(path) }.map { |path| File.expand_path(path) }.to_set
     end
 
-    def expected_constant_for(path, root)
+    def expected_constant_for(path, root, inflections = {})
       relative = Pathname(path).relative_path_from(Pathname(root)).to_s
       stem =
         case relative
@@ -67,12 +67,17 @@ module ArchSpec
           return nil
         end
 
-      camelize_path(stem)
+      camelize_path(stem, inflections)
     end
 
-    def camelize_path(path)
+    # Rails-style acronyms: inflections apply to whole path segments first,
+    # then to each snake_case word (inflect "api" => "API" fixes both api.rb
+    # and api_client.rb).
+    def camelize_path(path, inflections = {})
       path.split('/').map do |part|
-        part.split('_').map { |word| word[0] ? word[0].upcase + word[1..] : word }.join
+        inflections[part] || part.split('_').map do |word|
+          inflections[word] || (word[0] ? word[0].upcase + word[1..] : word)
+        end.join
       end.join('::')
     end
 
@@ -164,6 +169,12 @@ module ArchSpec
         extend: :extends
       }.freeze
 
+      ATTR_MESSAGES = {
+        attr_reader: %i[reader],
+        attr_writer: %i[writer],
+        attr_accessor: %i[reader writer]
+      }.freeze
+
       def visit(graph, path, node, current_constant: nil, namespace: [])
         return unless node
 
@@ -197,15 +208,25 @@ module ArchSpec
         )
 
         if node.superclass
-          superclass = constant_reference_name(node.superclass)
-          constant.superclass = superclass
-          graph.add_edge(
-            type: :inherits_from,
-            from_path: path,
-            from_constant: constant.name,
-            to: superclass,
-            location: SourceLocation.from_prism(path, node.superclass.location)
-          )
+          superclass = constant_reference_name(node.superclass) if constant_node?(node.superclass)
+
+          if superclass
+            constant.superclass = superclass
+            graph.add_edge(
+              type: :inherits_from,
+              from_path: path,
+              from_constant: constant.name,
+              to: superclass,
+              location: SourceLocation.from_prism(path, node.superclass.location)
+            )
+          else
+            # Dynamic superclass (Struct.new, DelegateClass(...)): no
+            # inherits_from edge, but constants inside still count as
+            # references, and ancestry stays marked unresolved.
+            constant.superclass = node.superclass.slice
+            visit(graph, path, node.superclass, current_constant: constant.name,
+                                                namespace: constant.name.split('::'))
+          end
         end
 
         visit(graph, path, node.body, current_constant: constant.name, namespace: constant.name.split('::'))
@@ -277,6 +298,8 @@ module ArchSpec
           )
         end
 
+        record_generated_methods(graph, path, node, message, current_constant, location)
+
         if (edge_type = MIXIN_MESSAGES[message])
           constant_arguments(node).each do |constant_name|
             if current_constant && (constant = graph.constants_named(current_constant).find do |candidate|
@@ -300,7 +323,8 @@ module ArchSpec
           from_path: path,
           from_constant: current_constant,
           to: message,
-          location: location
+          location: location,
+          receiver: receiver_kind(node)
         )
 
         if DYNAMIC_MESSAGES.include?(message)
@@ -318,11 +342,14 @@ module ArchSpec
       end
 
       def add_constant_reference(graph, path, node, current_constant)
+        name = constant_reference_name(node)
+        return unless name
+
         graph.add_edge(
           type: :references_constant,
           from_path: path,
           from_constant: current_constant,
-          to: constant_reference_name(node),
+          to: name,
           location: SourceLocation.from_prism(path, node.location)
         )
       end
@@ -349,27 +376,76 @@ module ArchSpec
         end || []
       end
 
+      # attr_* and unprefixed delegate calls define instance methods; without
+      # them, a class calling its own reader looks like a foreign call.
+      def record_generated_methods(graph, path, node, message, current_constant, location)
+        return unless current_constant && node.receiver.nil?
+        return unless ATTR_MESSAGES.key?(message) || message == :delegate
+
+        constant = graph.constants_named(current_constant).find { |candidate| candidate.path == path }
+        return unless constant
+
+        names = symbol_arguments(node)
+        return if message == :delegate && keyword_argument?(node, :prefix)
+
+        names.each do |name|
+          kinds = ATTR_MESSAGES.fetch(message, %i[reader])
+          constant.add_instance_method(name, location: location) if kinds.include?(:reader)
+          constant.add_instance_method(:"#{name}=", location: location) if kinds.include?(:writer)
+        end
+      end
+
+      def symbol_arguments(node)
+        node.arguments&.arguments&.filter_map do |argument|
+          argument.unescaped.to_sym if argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)
+        end || []
+      end
+
+      def keyword_argument?(node, name)
+        node.arguments&.arguments&.any? do |argument|
+          argument.is_a?(Prism::KeywordHashNode) && argument.elements.any? do |element|
+            element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode) &&
+              element.key.unescaped.to_sym == name
+          end
+        end
+      end
+
+      def receiver_kind(node)
+        receiver = node.receiver
+        return :none if receiver.nil? || receiver.is_a?(Prism::SelfNode)
+        return :constant if constant_node?(receiver)
+
+        :other
+      end
+
       def instantiates_and_invokes(node)
         receiver = node.receiver
         return unless receiver.is_a?(Prism::CallNode) && receiver.message&.to_sym == :new
 
-        name = constant_node?(receiver.receiver) ? constant_reference_name(receiver.receiver) : receiver.receiver&.slice
+        receiver_node = receiver.receiver
+        name = (constant_reference_name(receiver_node) if constant_node?(receiver_node)) || receiver_node&.slice
         "#{name}##{node.message}"
       end
 
+      # class Users::RolesController inside module Admin defines
+      # Admin::Users::RolesController, so compact paths join the namespace too.
       def qualified_constant_name(node, namespace)
         raw = constant_reference_name(node)
         absolute = node.respond_to?(:full_name_parts) && node.full_name_parts.first == :""
 
-        if absolute || raw.include?('::') || namespace.empty?
+        if absolute || namespace.empty?
           raw
         else
           "#{namespace.join('::')}::#{raw}"
         end
       end
 
+      # nil when the path has dynamic parts (self.class::FOO): there is no
+      # static name to check against.
       def constant_reference_name(node)
         node.full_name.to_s.sub(/\A::/, '')
+      rescue Prism::ConstantPathNode::DynamicPartsInConstantPathError
+        nil
       end
 
       def constant_node?(node)

data/lib/archspec/architectures.rb

@@ -1,6 +1,42 @@
 # 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. Keeps
+  #   controller APIs out of models and services. Options: +components:+,
+  #   +controller_api:+, +share_helpers:+.
+  # +:rails_strict+:: +:rails+ plus Zeitwerk name checks, a cycle check, and a
+  #   concern independence check. Options add +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:+.
+  #
+  # See the guides at https://archspecrb.dev/architectures/ for each in depth.
   module Architectures
     extend self
 
@@ -54,6 +90,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 +103,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,7 +139,12 @@ 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
@@ -94,30 +154,38 @@ module ArchSpec
       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)
 
+      forbidden = share_helpers ? %i[controllers] : %i[controllers helpers]
       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)
+      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)
+      rails_mvc(dsl, components: components, controller_api: controller_api, share_helpers: share_helpers)
       dsl.verify_zeitwerk_names!
       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:)
@@ -161,13 +229,16 @@ 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)
+
+        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)
@@ -226,5 +297,11 @@ 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
+    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
 
@@ -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)
@@ -205,7 +231,7 @@ module ArchSpec
       <<~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,17 +21,23 @@ module ArchSpec
       'vendor/**/*'
     ].freeze
 
-    attr_accessor :name, :root_path, :baseline_path
-    attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules
+    attr_accessor :name, :root_path, :todo_path, :base_dir
+    attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules, :inflections
 
     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 = {}
       @rules = []
+      @inflections = {}
+    end
+
+    def add_inflections(map)
+      @inflections.merge!(map.to_h.transform_keys(&:to_s).transform_values(&:to_s))
     end
 
     def add_source_patterns(patterns)
@@ -54,8 +64,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