archspec 1.1.0 → 1.2.0

data/lib/archspec/facts.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'tempfile'
+require 'yaml'
+
+module ArchSpec
+  # Shared semantic facts and versioned snapshots. Static framework passes and
+  # explicit runtime producers use Builder; checks import data without booting.
+  module Facts
+    extend self
+
+    VERSION = 2
+    LIST_KEYS = %w[references methods mixins exposures gaps receivers resolves].freeze
+    # Files outside the analyzed source that can change what any producer
+    # observes. A change to one of them invalidates a whole document.
+    DEFAULT_INPUTS = ['config/**/*.{rb,yml,yaml}', 'Gemfile', 'Gemfile.lock', '*.gemspec', '.ruby-version'].freeze
+    STALE_RULE = 'facts.stale'
+
+    # The exact input map of a version 1 document: every analyzed file plus the
+    # default inputs.
+    def snapshot(graph, excluding: 'archspec_facts')
+      paths = graph.files.keys + input_files(graph, DEFAULT_INPUTS, excluding: excluding)
+      digests(graph, paths.reject { |path| excluded?(graph, path, excluding) })
+    end
+
+    # A version 2 fingerprint: the producer's global inputs, the analyzed files
+    # its source patterns cover, and every file the facts cite.
+    def fingerprint(graph, inputs:, sources:, cited:, excluding:)
+      paths = input_files(graph, inputs, excluding: excluding) + source_files(graph, sources) +
+              cited.select { |path| File.file?(path) }
+      digests(graph, paths)
+    end
+
+    def input_files(graph, patterns, excluding:)
+      patterns.flat_map { |pattern| Dir.glob(File.join(graph.root, pattern)) }
+              .select { |path| File.file?(path) }.map { |path| File.expand_path(path) }
+              .reject { |path| excluded?(graph, path, excluding) }
+    end
+
+    # Source patterns match analyzed files only, so covering a directory never
+    # walks the file system.
+    def source_files(graph, patterns)
+      return [] if patterns.empty?
+
+      graph.files.values.select do |file|
+        patterns.any? { |pattern| File.fnmatch?(pattern, file.relative_path, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+      end.map(&:path)
+    end
+
+    def digest(path)
+      Digest::SHA256.file(path).hexdigest if File.file?(path)
+    end
+
+    # Loads every document in the directory. Stale documents and the facts of
+    # stale files are skipped and reported as diagnostics; everything else is
+    # validated before any of it is applied. Every named +producers+ must
+    # have written its document, so a producer that never succeeded cannot
+    # pass unnoticed.
+    def load_into(graph, directory, producers: [])
+      paths = Dir.glob(File.join(File.expand_path(directory, graph.root), '*.yml')).sort
+      raise Error, "no facts found in #{directory}; run `archspec reflect` or your facts producer" if paths.empty?
+
+      missing = producers.map(&:to_s) - paths.map { |path| File.basename(path, '.yml') }
+      unless missing.empty?
+        raise Error, "no facts from #{missing.join(', ')} in #{directory}; run `archspec reflect`"
+      end
+
+      batches = paths.filter_map do |path|
+        document = Document.new(graph, YAML.safe_load_file(path, permitted_classes: [], aliases: false), path)
+        document.compile_fresh(excluding: directory)
+      end
+      Application.apply(graph, batches)
+    rescue Psych::Exception, SystemCallError => error
+      raise Error, "could not load facts: #{error.message}"
+    end
+
+    def write(path, document)
+      FileUtils.mkdir_p(File.dirname(path))
+      Tempfile.create(['.archspec-facts-', '.yml'], File.dirname(path)) do |file|
+        file.write(document.to_yaml)
+        file.flush
+        file.close
+        File.chmod(0o666 & ~File.umask, file.path)
+        File.rename(file.path, path)
+      end
+    rescue SystemCallError => error
+      raise Error, "could not write facts #{path}: #{error.message}"
+    end
+
+    private
+
+    def excluded?(graph, path, excluding)
+      excluded = File.expand_path(excluding, graph.root)
+      path == excluded || path.start_with?("#{excluded}/")
+    end
+
+    def digests(graph, paths)
+      root = Pathname(graph.root)
+      paths.uniq.sort.to_h { |path| [Pathname(path).relative_path_from(root).to_s, digest(path)] }
+    end
+  end
+end
+
+require_relative 'facts/application'
+require_relative 'facts/document'
+require_relative 'facts/builder'

data/lib/archspec/formatters/explanation.rb

@@ -114,7 +114,8 @@ module ArchSpec
         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}"
+          source = edge.producer ? style.note(" (from #{edge.producer} facts)") : ''
+          output.puts "    #{style.faint(gutter)} #{edge.verb} #{edge.to}#{source}"
         end
       end
 

data/lib/archspec/formatters/json.rb

@@ -7,14 +7,17 @@ module ArchSpec
     module JSON
       module_function
 
-      def print(output = $stdout, graph:, diagnostics:)
-        output.puts ::JSON.pretty_generate(
+      def print(output = $stdout, graph:, diagnostics:, obsolete_todo: nil)
+        report = {
           files: graph.files.size,
           constants: graph.constants.size,
           facts: graph.edges.size,
           analysis: graph.analysis_census,
           violations: diagnostics.map { |diagnostic| diagnostic.to_h(root: graph.root) }
-        )
+        }
+        report[:obsolete_todo] = obsolete_todo if obsolete_todo
+
+        output.puts ::JSON.pretty_generate(report)
       end
     end
   end

data/lib/archspec/formatters/text.rb

@@ -24,15 +24,18 @@ module ArchSpec
 
       module_function
 
-      def print(output = $stdout, graph:, diagnostics:)
+      def print(output = $stdout, graph:, diagnostics:, obsolete_todo: nil)
+        style = Style.new(output)
+        print_obsolete_todo(output, style, obsolete_todo) if obsolete_todo&.any?
+
         if diagnostics.empty?
-          output.puts "ArchSpec passed: #{graph.files.size} files, #{graph.constants.size} constants, " \
+          verdict = obsolete_todo&.any? ? 'ArchSpec found no violations' : 'ArchSpec passed'
+          output.puts "#{verdict}: #{graph.files.size} files, #{graph.constants.size} constants, " \
                       "#{graph.edges.size} facts checked."
           print_census(output, graph)
           return
         end
 
-        style = Style.new(output)
         sources = Hash.new { |hash, path| hash[path] = read_lines(path) }
 
         diagnostics.each do |diagnostic|
@@ -44,6 +47,22 @@ module ArchSpec
         print_census(output, graph)
       end
 
+      def print_obsolete_todo(output, style, entries)
+        label = entries.size == 1 ? 'obsolete todo entry matches' : 'obsolete todo entries match'
+        output.puts "#{style.severity('[error]')} #{style.bold("#{entries.size} #{label} no current violation")}"
+        output.puts
+        entries.each do |entry|
+          detail = [entry['path'], entry['message']].compact.join(': ')
+          detail = entry['id'] if detail.empty?
+          rule = entry['rule'] ? " #{style.faint("[#{entry['rule']}]")}" : ''
+          output.puts "  #{detail}#{rule}"
+          output.puts "    #{style.faint(entry['evidence'])}" if entry['evidence']
+        end
+        output.puts
+        output.puts "  #{style.note('note:')} fixed or suppressed locally; run `archspec check --update-todo` to drop them"
+        output.puts
+      end
+
       def print_diagnostic(output, style, graph, diagnostic, sources)
         location = diagnostic.location
         relative = location.relative_path(graph.root)

data/lib/archspec/model.rb

@@ -49,6 +49,12 @@ module ArchSpec
   end
   MethodDefinition = Data.define(:owner, :name, :scope, :location, :visibility, :signatures, :alias_target)
 
+  # A concern callback whose effects depend on control flow. The static pass
+  # records it as a gap; a runtime producer can observe which of these
+  # candidate mixins and methods a consumer actually received.
+  ConditionalCallback = Data.define(:concern, :path, :kind, :location, :mixins, :methods)
+  ConditionalMixin = Data.define(:kind, :target, :location)
+
   Suppression = Data.define(:rule, :start_line, :end_line, :reason) do
     def matches?(diagnostic)
       (rule.nil? || rule == diagnostic.rule) &&
@@ -86,7 +92,8 @@ module ArchSpec
       @mixins = {
         include: Set.new,
         prepend: Set.new,
-        extend: Set.new
+        extend: Set.new,
+        singleton_prepend: Set.new
       }
     end
 
@@ -138,7 +145,8 @@ module ArchSpec
     :resolved_to,
     :resolved_receiver,
     :receiver_scope,
-    :resolved_method
+    :resolved_method,
+    :producer
   ) do
     VERBS = {
       references_constant: 'references',
@@ -200,7 +208,8 @@ module ArchSpec
 
     RESOLVED_ROOTS = %w[Object BasicObject].freeze
 
-    attr_reader :root, :files, :constants, :edges, :components, :analysis_diagnostics
+    attr_reader :root, :files, :constants, :edges, :components, :analysis_diagnostics, :conditional_callbacks,
+                :fact_diagnostics
 
     def initialize(root)
       @root = File.expand_path(root)
@@ -210,8 +219,11 @@ module ArchSpec
       @edges = []
       @components = {}
       @analysis_diagnostics = []
+      @conditional_callbacks = []
+      @fact_diagnostics = []
       @effective_definition_cache = {}
       @effective_method_cache = {}
+      @method_exposures = {}
     end
 
     def add_file(path:, parse_errors:, suppressions: [])
@@ -240,7 +252,7 @@ module ArchSpec
 
     def add_edge(type:, from_path:, from_constant:, to:, location:, confidence: :high, receiver: nil,
                  lexical_nesting: nil, resolved_to: nil, resolved_receiver: nil, receiver_scope: nil,
-                 resolved_method: nil)
+                 resolved_method: nil, producer: nil)
       nesting = lexical_nesting&.map { |name| normalize_constant(name) }&.freeze
       edges << Edge.new(
         type,
@@ -254,7 +266,8 @@ module ArchSpec
         resolved_to,
         resolved_receiver,
         receiver_scope,
-        resolved_method
+        resolved_method,
+        producer
       )
     end
 
@@ -273,6 +286,14 @@ module ArchSpec
       @constants_by_name[normalize_constant(name)]
     end
 
+    # Classes and modules that include or prepend the named module.
+    def consumers_of(name)
+      absolute = "::#{normalize_constant(name)}"
+      constants.select do |constant|
+        !constant.namespace_only && constant.mixins.values_at(:include, :prepend).any? { |names| names.include?(absolute) }
+      end
+    end
+
     def constants_for_path(path)
       constants.select { |constant| constant.path == path }
     end
@@ -281,13 +302,28 @@ module ArchSpec
       component = components[name.to_sym]
       return [] unless component
 
-      constants_for_component(name).flat_map(&:method_definitions)
+      expose_method_definitions(constants_for_component(name).flat_map(&:method_definitions))
     end
 
     # Every method definition in the graph, across all constants. Used by
     # project-wide naming rules that are not scoped to one component.
     def method_definitions
-      constants.flat_map(&:method_definitions)
+      expose_method_definitions(constants.flat_map(&:method_definitions))
+    end
+
+    # A module can supply an API on another object's class side while its
+    # actual instance methods remain available for ordinary Ruby lookup.
+    def expose_instance_methods(name, as_owner:, scope:)
+      @method_exposures[name] = [as_owner, scope]
+    end
+
+    def method_exposure(name)
+      @method_exposures[name]
+    end
+
+    def clear_method_caches
+      @effective_definition_cache.clear
+      @effective_method_cache.clear
     end
 
     def assign_components(component_specs)
@@ -312,7 +348,7 @@ module ArchSpec
         constants.each do |constant|
           matched_file = files_matched_by_pattern.include?(constant.path) && !defers_to_real_definition?(constant)
           matched_constant = spec.matches_constant?(constant.name)
-          matched_ancestor = spec.matching_ancestor(constant.name, self)
+          matched_ancestor = !excluded_files.include?(constant.path) && spec.matching_ancestor(constant.name, self)
           next unless matched_file || matched_constant || matched_ancestor
 
           component.add_file(constant.path, reason: "defines #{constant.name}") if matched_constant || matched_ancestor
@@ -411,7 +447,11 @@ module ArchSpec
       ancestors = Set.new
       unresolved = Set.new
       nodes.each do |node|
-        mixins = scope == :class ? node.mixins[:extend] : node.mixins[:prepend] | node.mixins[:include]
+        mixins = if scope == :class
+                   node.mixins[:singleton_prepend] | node.mixins[:extend]
+                 else
+                   node.mixins[:prepend] | node.mixins[:include]
+                 end
         mixins.each do |ancestor|
           resolved = resolve_constant_reference(ancestor, node.name, lexical_nesting: [node.name] + node.nesting)
           ancestors.add(resolved)
@@ -461,9 +501,8 @@ module ArchSpec
       visible_names = Set.new
       unresolved = Set.new
 
-      if scope == :instance
-        append_mixin_definitions(nodes, :prepend, definitions, visible_names, unresolved, visited)
-      end
+      prepend_kind = scope == :class ? :singleton_prepend : :prepend
+      append_mixin_definitions(nodes, prepend_kind, definitions, visible_names, unresolved, visited)
 
       own = nodes.flat_map { |node| node.method_definitions.select { |definition| definition.scope == scope } }
       append_visible_definitions(definitions, visible_names, own)
@@ -555,6 +594,13 @@ module ArchSpec
 
     private
 
+    def expose_method_definitions(definitions)
+      definitions.map do |definition|
+        exposure = @method_exposures[definition.owner] if definition.scope == :instance
+        exposure ? definition.with(owner: exposure.first, scope: exposure.last) : definition
+      end
+    end
+
     def append_mixin_definitions(nodes, kind, definitions, visible_names, unresolved, visited)
       mixins = nodes.flat_map do |node|
         node.mixins[kind].map { |ancestor| [node, ancestor] }

data/lib/archspec/producer.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  # A named source of runtime facts. <tt>archspec reflect</tt> runs each
+  # producer declared in +Archspec.rb+ in its own process: it boots the
+  # framework, analyzes the source, lets the producer record what it observes
+  # through a Facts::Builder, and writes <tt><facts>/<name>.yml</tt>.
+  #
+  #   ArchSpec.producer :widgets do
+  #     inputs "config/widgets.yml"          # global: a change invalidates every fact
+  #     sources "app/widgets/**/*.rb"        # per file: a change invalidates that file's facts
+  #     env "WIDGETS_ENV"                    # must match when a check sets it
+  #
+  #     boot { |root| require File.join(root, "config/environment") }
+  #
+  #     capture do |facts|
+  #       Widgets.registry.each do |widget, service|
+  #         facts.reference(source: widget, target: service, location: widget.declaration_site)
+  #       end
+  #     end
+  #   end
+  #
+  # Checks never run producers; they read the files they wrote.
+  class Producer
+    attr_reader :name, :input_patterns, :source_patterns, :env_names
+
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      def register(name, &block)
+        registry[name.to_s] = new(name, &block)
+      end
+
+      # Requires the file a declaration names, then returns the registered
+      # producer. Paths starting with a dot resolve against +Archspec.rb+.
+      def load(name, definition)
+        path = definition.producers.fetch(name.to_s) do
+          raise Error, "producer #{name} is not declared; add `reflect :#{name}` to Archspec.rb"
+        end
+        if path
+          require(path.start_with?('.') ? File.expand_path(path, definition.base_dir || Dir.pwd) : path)
+        end
+        registry.fetch(name.to_s) do
+          raise Error, "no producer named #{name} is registered#{" by #{path}" if path}"
+        end
+      rescue Error
+        raise
+      rescue StandardError, ScriptError => error
+        # A syntax error's message already names the file and line.
+        frame = origin(error, definition.base_dir || Dir.pwd) unless error.is_a?(SyntaxError)
+        raise Error, "could not load producer #{name}: #{error.message.strip} (#{error.class})#{frame}"
+      end
+
+      # The first backtrace frame in the project, which is usually where the
+      # fix belongs.
+      def origin(error, root)
+        frames = Array(error.backtrace)
+        frame = frames.find { |line| line.start_with?("#{root}/") && !line.include?('/vendor/') } || frames.first
+        frame ? "\n  at #{frame.delete_prefix("#{root}/")}" : ''
+      end
+    end
+
+    def initialize(name, &block)
+      @name = name.to_s
+      @input_patterns = Facts::DEFAULT_INPUTS.dup
+      @source_patterns = []
+      @env_names = []
+      block.arity == 1 ? yield(self) : instance_eval(&block) if block
+      raise Error, "producer #{@name} has no capture block" unless @capture
+    end
+
+    # Files outside the analyzed source whose change invalidates the whole
+    # document. The defaults cover +config/+, the Gemfile and lockfile,
+    # gemspecs, and the Ruby version.
+    def inputs(*patterns)
+      @input_patterns |= patterns.flatten.map(&:to_s)
+    end
+
+    # Analyzed files this producer inspects. A changed, added, or removed file
+    # invalidates only the facts it contributed. Files the facts cite are
+    # always covered.
+    def sources(*patterns)
+      @source_patterns |= patterns.flatten.map(&:to_s)
+    end
+
+    # Environment variables whose values shape what the producer observes.
+    # They are recorded as captured, so do not name secrets.
+    def env(*names)
+      @env_names |= names.flatten.map(&:to_s)
+    end
+
+    def boot(&block)
+      @boot = block
+    end
+
+    def capture(&block)
+      @capture = block
+    end
+
+    # Boots, analyzes, and captures; returns the validated document.
+    def run(definition, root)
+      begin
+        instance_exec(root, &@boot) if @boot
+      rescue Error
+        raise
+      rescue StandardError, ScriptError => error
+        raise Error, "could not boot: #{error.message.strip} (#{error.class})#{origin(error, root)}"
+      end
+      graph = Analyzer.analyze(definition, root: root, include_facts: false)
+      raise Error, 'cannot reflect source with syntax errors' if graph.files.values.any? { |file| file.parse_errors.any? }
+
+      facts = Facts::Builder.new(graph, producer: name)
+      begin
+        instance_exec(facts, &@capture)
+      rescue Error
+        raise
+      rescue StandardError, ScriptError => error
+        raise Error, "capture failed: #{error.message.strip} (#{error.class})#{origin(error, root)}"
+      end
+      facts.to_document(facts_path: definition.facts_path, inputs: input_patterns, sources: source_patterns,
+        env: env_names.filter_map { |variable| [variable, ENV[variable]] if ENV[variable] }.to_h)
+    end
+
+    private
+
+    def origin(error, root)
+      self.class.origin(error, root)
+    end
+  end
+
+  # Registers a facts producer. See ArchSpec::Producer.
+  def self.producer(name, &block)
+    Producer.register(name, &block)
+  end
+end