archspec 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c675a4a926497ac7ff0228a2eebe90ad4eddb39463bdbbcd1732f60f078ba5e
-  data.tar.gz: 2bbde647e0e899bba0a20f7953028506cfb0dcc756101a75bd4c49c11282624e
+  metadata.gz: bb5f7cda6a11326fedead006aa062155c7fdb2e1a3ea6e374d5cd1bca45d17e9
+  data.tar.gz: 417ad99fbfc27aa871fcb0bd4ce3ced72d8c1aad3810d35f51722586a151bf81
 SHA512:
-  metadata.gz: c42af70bb7cfb04ad3f0feca6dc429b14bc1f9e55eb3b4001f4fd11aead8ca0061b22c14097def6b182d09435764e9c44e0132f02b4964718ba47fc64ee37544
-  data.tar.gz: 3505aa0af7fc166ce59d316eda7dfbe4deb24dbede4bbbc507f4516b82d0090c9c8b3eba4f70c3379978be6a9f582c6bb742c9416ac0b63529bb5f68aa90eb1b
+  metadata.gz: 2dc335e5f43af785346921ca4b57e699a5b748d80e09441ac3abe6123ba7b17a730dba2a7c0f7c4c0c11b6288dc7e79ee87e95d8f9454a167df7d98a98de88d5
+  data.tar.gz: 8b5736b3d23a1c053f8e158636a8582184c9c924ce478e1019818b527960ada6c8d5d7ab4e581849564978ae4c4f05d4238c0a571bf8d78ef479fb6242bc3868

data/README.md

@@ -18,7 +18,7 @@ Battle tested in [<picture><source media="(prefers-color-scheme: dark)" srcset="
 
 ---
 
-ArchSpec turns your architecture into executable checks: components, layers, constant references, inheritance, mixins, named method calls, method protocols, naming conventions, cycles, and Rails boundaries. It is plain static analysis: Rubydex builds the semantic index, Prism supplies a small syntax overlay, the app never boots, and no AI is involved in checking your code.
+ArchSpec turns your architecture into executable checks: components, layers, constant references, inheritance, mixins, named method calls, method protocols, naming conventions, cycles, and Rails boundaries. Checking is plain static analysis: Rubydex builds the semantic index, Prism supplies a small syntax overlay, the app never boots during a check, and no AI is involved in checking your code.
 
 ## Why ArchSpec?
 
@@ -122,6 +122,7 @@ architecture :cqrs,
 ## What It Checks
 
 - **Dependencies:** allowed and forbidden references between components, in both directions
+- **Rails reflection:** opt-in runtime capture of association targets, custom validators, and conditional concern effects, enforced by later static checks
 - **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
@@ -177,6 +178,18 @@ bundle exec archspec check --update-todo
 bundle exec archspec explain app/models/user.rb
 ```
 
+To check dependencies Rails resolves at runtime, such as association targets
+and custom validators, add `reflect :rails` to `Archspec.rb` and run
+`bundle exec archspec reflect --environment test`. It boots the app once, in a
+separate process, and saves what Rails resolved. Checks read those facts
+without booting anything, and fail with `facts.stale` for files edited since.
+Locally, `archspec check --reflect` refreshes stale facts before checking.
+See the [Rails reflection guide](https://archspecrb.dev/association-reflection/).
+
+Other frameworks and macro libraries can supply facts with a small producer
+that the same command runs. See the
+[framework integration guide](https://archspecrb.dev/framework-integrations/).
+
 `explain` shows why a file or constant belongs to a component, its resolved
 ancestry, outgoing facts, incoming dependencies, and anything the analysis
 could not prove:
@@ -236,6 +249,13 @@ todo "archspec_todo.yml"
 bundle exec archspec check --update-todo
 ```
 
+In CI, add `--check-todo` so a fixed violation that is still listed fails the
+build instead of rotting in the file:
+
+```sh
+bundle exec archspec check --check-todo
+```
+
 Use local suppressions for deliberate exceptions:
 
 ```ruby

data/lib/archspec/analyzer.rb

@@ -3,43 +3,57 @@
 require 'prism'
 require 'set'
 
+require_relative 'sources/ruby'
+require_relative 'sources/erb'
+
 module ArchSpec
   module Analyzer
     extend self
 
-    def analyze(definition, root:)
+    SOURCES = [Sources::Ruby, Sources::Erb].freeze
+
+    def analyze(definition, root:, include_facts: true)
       root = File.expand_path(root)
       graph = Graph.new(root)
-      paths = ruby_files(definition, root)
       syntax = SyntaxOverlay.new
-
-      paths.each do |path|
-        result = Prism.parse_file(path)
-        graph.add_file(
-          path: path,
-          parse_errors: parse_errors_for(path, result.errors),
-          suppressions: suppressions_for(result.comments)
-        )
-        syntax.scan(path, result.value) if result.value
+      index_paths = []
+
+      all_extensions = SOURCES.flat_map(&:extensions)
+      paths = source_files(definition, root, all_extensions)
+      SOURCES.each do |source_class|
+        source_class_paths = paths.select { |path| path.end_with?(*source_class.extensions) }
+        index_paths.concat(source_class_paths) if source_class.rubydex_indexable?
+
+        source_class_paths.each do |path|
+          source = source_class.new(path)
+          graph.add_file(
+            path: source.path,
+            parse_errors: source.parse_errors,
+            suppressions: SuppressionParser.parse(source.comments)
+          )
+          syntax.scan(source.path, source.prism)
+        end
       end
 
       method_names = definition.rules.grep(Rules::CannotCallRule).flat_map(&:method_names)
-      index = RubydexIndex.new(paths, syntax: syntax, method_names: method_names)
+      index = RubydexIndex.new(index_paths, syntax: syntax, method_names: method_names)
       index.populate(graph)
       syntax.apply(graph, call_resolutions: index.call_resolutions)
+      syntax.apply_concerns(graph)
+      Facts.load_into(graph, definition.facts_path, producers: definition.declared_producers) if include_facts && definition.facts_path
       graph.assign_components(definition.component_specs.values)
       graph
     end
 
     private
 
-    def ruby_files(definition, root)
+    def source_files(definition, root, extensions)
       ignored = ignored_files(definition, root)
 
       definition.analysis_patterns.flat_map do |pattern|
         Dir.glob(File.absolute_path(pattern, root))
       end.select do |path|
-        File.file?(path) && path.end_with?('.rb')
+        File.file?(path) && path.end_with?(*extensions)
       end.map do |path|
         File.expand_path(path)
       end.uniq.reject do |path|
@@ -48,19 +62,26 @@ module ArchSpec
     end
 
     def ignored_files(definition, root)
-      definition.ignore_patterns.flat_map do |pattern|
-        Dir.glob(File.absolute_path(pattern, root))
-      end.select { |path| File.file?(path) }.map { |path| File.expand_path(path) }.to_set
+      glob_files(definition.ignore_patterns, root) - claimed_files(definition, root)
     end
 
-    def suppressions_for(comments)
-      SuppressionParser.parse(comments)
+    # Files a component pattern explicitly claims inside a default-ignored
+    # directory, minus its +except:+ matches and anything the user ignored.
+    def claimed_files(definition, root)
+      claimed = definition.component_specs.values.flat_map do |spec|
+        patterns = spec.file_patterns.select { |pattern| definition.claims_default_ignored?(pattern) }
+        next [] if patterns.empty?
+
+        (glob_files(patterns, root) - glob_files(spec.exclude_patterns, root)).to_a
+      end.to_set
+
+      claimed.empty? ? claimed : claimed - glob_files(definition.user_ignore_patterns, root)
     end
 
-    def parse_errors_for(path, errors)
-      errors.map do |error|
-        ParseError.new(error.message, SourceLocation.from_prism(path, error.location))
-      end
+    def glob_files(patterns, root)
+      patterns.flat_map do |pattern|
+        Dir.glob(File.absolute_path(pattern, root))
+      end.select { |path| File.file?(path) }.map { |path| File.expand_path(path) }.to_set
     end
 
     module SuppressionParser
@@ -74,8 +95,8 @@ module ArchSpec
         active = Hash.new { |hash, key| hash[key] = [] }
 
         sorted_comments(comments).each do |comment|
-          text = comment.slice.sub(/\A#\s?/, '').strip
-          line = comment.location.start_line
+          text = comment.text.sub(/\A#\s?/, '').strip
+          line = comment.line
 
           if (match = text.match(DISABLE_PATTERN))
             mode, rule, reason = match.captures
@@ -110,7 +131,7 @@ module ArchSpec
       private
 
       def sorted_comments(comments)
-        comments.sort_by { |comment| [comment.location.start_line, comment.location.start_column] }
+        comments.sort_by { |comment| [comment.line, comment.column] }
       end
 
       def normalize_rule(rule)
@@ -221,6 +242,7 @@ module ArchSpec
         @superclass_overrides = {}
         @superclass_fallbacks = {}
         @method_owner_overrides = []
+        @concerns = ConcernSemantics.new
       end
 
       def scan(path, node)
@@ -270,6 +292,10 @@ module ArchSpec
         @declaration_kinds[[normalize(name), path]]
       end
 
+      def apply_concerns(graph)
+        @concerns.apply(graph)
+      end
+
       def declaration_name(name, path = nil, location = nil)
         normalized = normalize(name)
         return normalized unless path
@@ -393,6 +419,7 @@ module ArchSpec
         end
 
         location = SourceLocation.from_prism(path, node.location)
+        @concerns.record_module(name, path, node.body)
         record_namespace(
           name,
           path,
@@ -447,8 +474,8 @@ module ArchSpec
         if kind == :class
           if static_superclass
             @superclass_fallbacks[[normalize(name), path]] = superclass
-          else
-            record_builder_superclass(name, path, node.value)
+          elsif superclass
+            @superclass_overrides[[normalize(name), path]] = superclass
           end
         end
 
@@ -671,22 +698,12 @@ module ArchSpec
         node.superclass.slice
       end
 
-      def record_builder_superclass(name, path, value)
-        argument = value.arguments&.arguments&.first
-        return if argument && constant_node?(argument)
-
-        receiver = constant_reference_name(value.receiver)&.sub(/\A::/, '')
-        return if receiver == 'Class'
-
-        @superclass_overrides[[normalize(name), path]] = "#{constant_reference_name(value.receiver)}.#{value.message}"
-      end
-
       def builder_superclass(value)
         argument = value.arguments&.arguments&.first
         return constant_reference_name(argument) if argument && constant_node?(argument)
 
         receiver = constant_reference_name(value.receiver)&.sub(/\A::/, '')
-        "#{constant_reference_name(value.receiver)}.#{value.message}" unless receiver == 'Class'
+        constant_reference_name(value.receiver) unless receiver == 'Class'
       end
 
       def singleton_target(expression, current_constant)

data/lib/archspec/cli.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
+require 'open3'
 require 'optparse'
+require 'rbconfig'
 
 module ArchSpec
   # The <tt>archspec</tt> command line. Backs the +exe/archspec+ executable and
-  # dispatches the +init+, +check+, +explain+, and +version+ subcommands.
+  # dispatches the +init+, +check+, +explain+, +reflect+, and +version+ subcommands.
   #
   #   archspec init
-  #   archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]
-  #   archspec explain PATH_OR_CONSTANT
+  #   archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo|--check-todo] [--reflect]
+  #   archspec explain PATH_OR_CONSTANT [--reflect]
   #
   # #run returns the process exit status: 0 when clean, 1 when violations are
-  # found.
+  # found (or, with <tt>--check-todo</tt>, when the todo lists violations that
+  # no longer occur).
   module CLI
     extend self
 
@@ -21,6 +24,8 @@ module ArchSpec
       architecture :rails
     RUBY
 
+    REFLECT_HELP = 'Run producers whose facts are missing or stale first (boots the app)'
+
     class UsageError < Error; end
 
     def run(argv, output: $stdout, error: $stderr)
@@ -33,9 +38,11 @@ module ArchSpec
       when 'init'
         init(argv, output)
       when 'check'
-        check(argv, output)
+        check(argv, output, error)
       when 'explain'
-        explain(argv, output)
+        explain(argv, output, error)
+      when 'reflect'
+        reflect(argv, output)
       when 'version', '--version', '-v'
         raise UsageError, "unexpected argument: #{argv.first}" if argv.any?
 
@@ -58,7 +65,7 @@ module ArchSpec
     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)
+      if subject && !%w[init check explain reflect version].include?(subject)
         raise UsageError, "unknown command: #{subject}"
       end
 
@@ -95,11 +102,13 @@ module ArchSpec
       raise Error, "could not create #{path}: #{e.message}"
     end
 
-    def check(argv, output)
+    def check(argv, output, error)
       options = {
         config: CONFIG_FILE,
         format: 'text',
         update_todo: false,
+        check_todo: false,
+        reflect: false,
         help: false
       }
 
@@ -110,6 +119,10 @@ module ArchSpec
         opts.on('--update-todo', 'Replace the configured todo with current violations') do
           options[:update_todo] = true
         end
+        opts.on('--check-todo', 'Also fail when the configured todo lists violations that no longer occur') do
+          options[:check_todo] = true
+        end
+        opts.on('--reflect', REFLECT_HELP) { options[:reflect] = true }
         opts.on('-h', '--help', 'Show this help') { options[:help] = true }
       end
       parser.parse!(argv)
@@ -120,38 +133,51 @@ module ArchSpec
       end
 
       raise Error, 'cannot combine --update-todo with path arguments' if options[:update_todo] && argv.any?
+      raise Error, 'cannot combine --update-todo with --check-todo' if options[:update_todo] && options[:check_todo]
 
       formatter = formatter_for(options[:format])
       definition, root = load_definition(options[:config])
-      graph = Analyzer.analyze(definition, root: root)
       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_todo] || options[:check_todo]) && !todo_path
+        raise Error, "no todo configured; add `todo \"archspec_todo.yml\"` to #{options[:config]}"
+      end
+
+      if options[:check_todo] && !File.exist?(todo_path)
+        raise Error, "todo file #{Pathname(todo_path).relative_path_from(Pathname(root))} does not exist; " \
+                     'run `archspec check --update-todo` to create it'
+      end
+
+      graph = analyze_with_facts(definition, root, options, error)
+      candidates = Evaluator.unsuppressed(definition, graph)
+      # Syntax errors and stale facts are never an accepted baseline; they must be fixed.
+      acceptable = candidates.reject { |diagnostic| ['parser.syntax', Facts::STALE_RULE].include?(diagnostic.rule) }
 
       if options[:update_todo]
-        unless todo_path
-          raise Error,
-                "no todo configured; add `todo \"archspec_todo.yml\"` to #{options[:config]}"
+        if candidates.any? { |diagnostic| diagnostic.rule == Facts::STALE_RULE }
+          raise Error, 'facts are out of date; run `archspec reflect` before updating the todo'
         end
 
-        # 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}."
+        count = Todo.write(todo_path, acceptable, root: root)
+        label = count == 1 ? 'entry' : 'entries'
+        output.puts "Updated #{Pathname(todo_path).relative_path_from(Pathname(root))} with #{count} #{label}."
         return 0
       end
 
-      formatter.print(output, graph: graph, diagnostics: diagnostics)
-      diagnostics.empty? ? 0 : 1
+      todo = Todo.load(todo_path, root: root)
+      diagnostics = candidates.reject { |diagnostic| todo.include?(diagnostic) }
+      diagnostics = scope_to_paths(diagnostics, argv, root, graph)
+      obsolete = scope_entries_to_paths(todo.unmatched_by(acceptable), argv, root) if options[:check_todo]
+
+      formatter.print(output, graph: graph, diagnostics: diagnostics, obsolete_todo: obsolete)
+      diagnostics.empty? && (obsolete.nil? || obsolete.empty?) ? 0 : 1
     end
 
-    def explain(argv, output)
-      options = { config: CONFIG_FILE, help: false }
+    def explain(argv, output, error)
+      options = { config: CONFIG_FILE, reflect: false, help: false }
       parser = OptionParser.new do |opts|
         opts.banner = usage('explain').strip
         opts.on('--config PATH', 'Use a different architecture file') { |value| options[:config] = value }
+        opts.on('--reflect', REFLECT_HELP) { options[:reflect] = true }
         opts.on('-h', '--help', 'Show this help') { options[:help] = true }
       end
       parser.parse!(argv)
@@ -166,11 +192,14 @@ module ArchSpec
       raise UsageError, "unexpected argument: #{argv.first}" if argv.any?
 
       definition, root = load_definition(options[:config])
-      graph = Analyzer.analyze(definition, root: root)
+      graph = analyze_with_facts(definition, root, options, error)
       Formatters::Explanation.print(output, graph: graph, subject: subject)
       0
     end
 
+    public
+
+    # Evaluates an +Archspec.rb+ file and returns the definition and its root.
     def load_definition(config_path)
       raise Error, "no #{config_path} found; run `archspec init` first" unless File.exist?(config_path)
 
@@ -193,17 +222,106 @@ module ArchSpec
       raise Error, "could not load #{config_path}: #{detail}"
     end
 
-    def scope_to_paths(diagnostics, paths, root)
+    private
+
+    def reflect(argv, output)
+      options = { config: CONFIG_FILE, environment: nil, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = usage('reflect')
+        opts.on('--config PATH', 'Use a different architecture file') { |value| options[:config] = value }
+        opts.on('--environment NAME', 'Set RAILS_ENV for the producers (default: RAILS_ENV or development)') do |value|
+          options[:environment] = value
+        end
+        opts.on('-h', '--help', 'Show this help') { options[:help] = true }
+      end
+      parser.parse!(argv)
+      if options[:help]
+        output.puts parser
+        return 0
+      end
+
+      definition, root = load_definition(options[:config])
+      require_facts(definition, options[:config])
+      names = argv.empty? ? definition.producers.keys : argv
+      undeclared = names - definition.producers.keys
+      raise UsageError, "undeclared producer: #{undeclared.first}" if undeclared.any?
+
+      run_producers(names, options[:config], root, output, environment: options[:environment])
+    end
+
+    # Analyzes with facts, first running the producers that --reflect or
+    # <tt>reflect auto: true</tt> select when their documents are missing,
+    # then again for any whose documents turn out stale.
+    def analyze_with_facts(definition, root, options, output)
+      require_facts(definition, options[:config]) if options[:reflect]
+      names = options[:reflect] ? definition.producers.keys : definition.auto_producers
+      return Analyzer.analyze(definition, root: root) if names.empty?
+
+      directory = File.expand_path(definition.facts_path, root)
+      missing = names.reject { |name| File.file?(File.join(directory, "#{name}.yml")) }
+      run_producers(missing, options[:config], root, output) if missing.any?
+      graph = Analyzer.analyze(definition, root: root)
+      stale = graph.fact_diagnostics.select { |diagnostic| diagnostic.rule == Facts::STALE_RULE }
+                   .map { |diagnostic| File.basename(diagnostic.evidence, '.yml') }.uniq & names
+      return graph if stale.empty?
+
+      run_producers(stale, options[:config], root, output)
+      Analyzer.analyze(definition, root: root)
+    end
+
+    def require_facts(definition, config_path)
+      return if definition.facts_path
+
+      raise Error, "no facts configured; add `reflect :rails` or `facts \"archspec_facts\"` to #{config_path}"
+    end
+
+    # Runs each producer in its own process, in parallel, and reports every
+    # failure after the others finish.
+    def run_producers(names, config_path, root, output, environment: nil)
+      env = { 'ARCHSPEC_REFLECTION_CONFIG' => File.expand_path(config_path) }
+      env['RAILS_ENV'] = environment if environment
+      runner = File.expand_path('reflect_runner.rb', __dir__)
+      results = names.map do |name|
+        Thread.new do
+          Open3.capture3(env.merge('ARCHSPEC_PRODUCER' => name), RbConfig.ruby, runner, chdir: root)
+        rescue SystemCallError => e
+          ['', e.message, nil]
+        end
+      end.map(&:value)
+
+      failures = names.zip(results).reject do |_, (stdout, _, status)|
+        output.print stdout
+        status&.success?
+      end
+      return 0 if failures.empty?
+
+      raise Error, failures.map { |name, (_, stderr, status)|
+        "#{name} producer failed#{" (exit #{status.exitstatus})" if status&.exitstatus}: #{stderr.strip}"
+      }.join("\n")
+    end
+
+    # A stale facts document affects every path, so it is always reported.
+    def scope_to_paths(diagnostics, paths, root, graph)
       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
+        within?(diagnostic.location.path, expanded) ||
+          (diagnostic.rule == Facts::STALE_RULE && !graph.files.key?(diagnostic.location.path))
       end
     end
 
+    def scope_entries_to_paths(entries, paths, root)
+      return entries if paths.empty?
+
+      expanded = paths.map { |path| File.expand_path(path, root) }
+      entries.select { |entry| entry['path'] && within?(File.expand_path(entry['path'], root), expanded) }
+    end
+
+    def within?(path, scopes)
+      scopes.any? { |scope| path == scope || path.start_with?("#{scope}/") }
+    end
+
     def todo_path_for(definition, root)
       return unless definition.todo_path
 
@@ -226,17 +344,20 @@ module ArchSpec
       when 'init'
         'Usage: archspec init [PATH] [--force]'
       when 'check'
-        'Usage: archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo]'
+        'Usage: archspec check [PATHS...] [--config PATH] [--format text|json] [--update-todo|--check-todo] [--reflect]'
       when 'explain'
-        'Usage: archspec explain PATH_OR_CONSTANT [--config PATH]'
+        'Usage: archspec explain PATH_OR_CONSTANT [--config PATH] [--reflect]'
+      when 'reflect'
+        'Usage: archspec reflect [PRODUCERS...] [--config PATH] [--environment NAME]'
       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 check [PATHS...] [--config PATH] [--format text|json] [--update-todo|--check-todo] [--reflect]
+            archspec explain PATH_OR_CONSTANT [--config PATH] [--reflect]
+            archspec reflect [PRODUCERS...] [--config PATH] [--environment NAME]
             archspec version
             archspec help [COMMAND]
         TEXT