archspec 1.1.0.rc2 → 1.2.0

data/lib/archspec/rails_reflector.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  # The built-in Rails producer. <tt>archspec reflect</tt> boots the
+  # application in a separate process and records what Rails itself resolved:
+  # association targets and generated methods, custom validator classes, and
+  # the effects conditional concern callbacks had on each consumer. Normal
+  # analysis never requires Rails.
+  module RailsReflector
+    extend self
+
+    ASSOCIATIONS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
+    # Macros that declare associations under derived names.
+    GENERATED_ASSOCIATIONS = {
+      has_one_attached: [[:has_one, '%s_attachment'], [:has_one, '%s_blob']],
+      has_many_attached: [[:has_many, '%s_attachments'], [:has_many, '%s_blobs']],
+      has_rich_text: [[:has_one, 'rich_text_%s']]
+    }.freeze
+    VALIDATIONS = %i[validates validates!].freeze
+    Site = Data.define(:macro, :name, :owner, :location)
+    # Module#name, immune to classes that redefine +name+ with other meanings.
+    MODULE_NAME = Module.instance_method(:name)
+
+    def boot(root)
+      environment = File.join(root, 'config/environment.rb')
+      raise Error, "no #{environment} found; the rails producer requires a Rails application" unless File.file?(environment)
+
+      ENV['RAILS_ENV'] ||= 'development'
+      require environment
+      eager_load_application
+    end
+
+    # Records every Rails fact for the loaded application.
+    def capture(facts, models: active_record_models, validated: validated_classes)
+      sites = macro_sites(facts.graph, models | validated)
+      associations(facts, models, sites)
+      validators(facts, validated, sites)
+      concerns(facts)
+      facts
+    end
+
+    def associations(facts, models, sites = macro_sites(facts.graph, models))
+      graph = facts.graph
+      reflections = models.flat_map(&:reflect_on_all_associations)
+                          .uniq { |reflection| [reflection.active_record.name, reflection.name] }
+      reflections.sort_by { |reflection| [reflection.active_record.name.to_s, reflection.name.to_s] }.each do |reflection|
+        model = reflection.active_record
+        next if model.name.nil? || graph.constants_named(model.name).empty?
+
+        ancestors = graph.ancestor_names(model.name).first | Set[model.name]
+        candidates = sites.fetch([reflection.macro, reflection.name.to_s], []).select { |site| ancestors.include?(site.owner) }
+        source = source_node(graph, model, candidates)
+        next unless source
+
+        if candidates.size != 1
+          facts.gap(source: source, location: source.location,
+            message: "association #{model.name}.#{reflection.name}: no unique literal declaration")
+          next
+        end
+        site = candidates.first
+        generated = model.generated_association_methods.instance_methods(false).map(&:to_s)
+        names = [reflection.name.to_s, "#{reflection.name}="] & generated
+        facts.methods(owner: source, location: site.location, names: names.sort) unless names.empty?
+        if reflection.polymorphic?
+          facts.gap(source: source, location: site.location, message: "polymorphic association #{model.name}.#{reflection.name}")
+          next
+        end
+        begin
+          facts.reference(source: source, target: reflection.klass, location: site.location)
+        rescue NameError, ArgumentError, ActiveRecord::ActiveRecordError, Error => error
+          facts.gap(source: source, location: site.location,
+            message: "unresolved association #{model.name}.#{reflection.name}: #{error.message.lines.first.strip}")
+        end
+      end
+    end
+
+    # A validation such as <tt>validates :email, email: true</tt> names its
+    # validator class only by convention. The loaded model knows the class
+    # Rails resolved; the literal +validates+ call supplies the location.
+    def validators(facts, classes, sites = macro_sites(facts.graph, classes))
+      graph = facts.graph
+      classes.to_h { |klass| [MODULE_NAME.bind_call(klass), klass] }.sort.each do |class_name, klass|
+        next if class_name.nil? || graph.constants_named(class_name).empty?
+
+        ancestors = graph.ancestor_names(class_name).first | Set[class_name]
+        klass.validators.map(&:class).uniq.map { |validator| MODULE_NAME.bind_call(validator) }.compact.sort.each do |name|
+          next if name.start_with?('ActiveModel::', 'ActiveRecord::')
+
+          candidates = VALIDATIONS.flat_map { |macro| sites.fetch([macro, :validator], []) }.select do |site|
+            ancestors.include?(site.owner) && validator_key?(site.name, name)
+          end
+          if candidates.empty?
+            next if referenced?(graph, ancestors, name)
+
+            source = source_node(graph, klass, [])
+            if source
+              facts.gap(source: source, location: source.location,
+                message: "validator #{name} on #{class_name}: no literal declaration")
+            end
+            next
+          end
+          candidates.each do |site|
+            source = site_source(graph, klass, site)
+            facts.reference(source: source, target: name, location: site.location) if source
+          end
+        end
+      end
+    end
+
+    # Conditional concern callbacks are gaps in static analysis. Once the
+    # application is loaded, each consumer shows which candidate mixins and
+    # methods it actually received. An effect is recorded only when exactly one
+    # candidate explains it; the gap is resolved only when every consumer could
+    # be inspected and every observed effect was attributed.
+    def concerns(facts)
+      graph = facts.graph
+      callbacks = graph.conditional_callbacks
+      return if callbacks.empty?
+
+      unsettled = callbacks.map(&:concern).uniq.reject { |concern| runtime_constant(concern) }.to_set
+      consumers(graph, callbacks).each do |node, applicable|
+        consumer = runtime_constant(node.name)
+        if consumer
+          unsettled.merge(observe_mixins(facts, node, consumer, applicable))
+          observe_methods(facts, node, consumer, applicable)
+        else
+          unsettled.merge(applicable.map(&:concern))
+        end
+      end
+      callbacks.each do |callback|
+        next if unsettled.include?(callback.concern)
+
+        source = graph.constants_named(callback.concern).find { |constant| constant.path == callback.path }
+        facts.resolve(source: source, location: callback.location, message: "conditional #{callback.kind} callback",
+          consumers: graph.consumers_of(callback.concern))
+      end
+    end
+
+    private
+
+    # Loads the application's own code, including engines inside the project,
+    # but not installed gems: their models are not analyzed, and loading them
+    # can require configuration the chosen environment does not have.
+    def eager_load_application
+      loader = Rails.autoloaders.main if defined?(Rails.autoloaders)
+      return Rails.application.eager_load! unless loader.respond_to?(:dirs) && loader.respond_to?(:eager_load_dir)
+
+      root = "#{Rails.root}/"
+      gems = (Gem.path + [defined?(Bundler) ? Bundler.bundle_path.to_s : nil]).compact.map { |path| "#{File.expand_path(path)}/" }
+      loader.dirs.select { |dir| dir.start_with?(root) && gems.none? { |gem_dir| dir.start_with?(gem_dir) } }
+            .each { |dir| loader.eager_load_dir(dir) }
+    end
+
+    def active_record_models
+      defined?(ActiveRecord::Base) ? ActiveRecord::Base.descendants.reject(&:abstract_class?).select(&:name) : []
+    end
+
+    def validated_classes
+      return [] unless defined?(ActiveModel::Validations)
+
+      ObjectSpace.each_object(Class).select { |klass| klass.include?(ActiveModel::Validations) && MODULE_NAME.bind_call(klass) }
+    end
+
+    # Returns the concerns whose observed effects could not be attributed to a
+    # single candidate declaration.
+    def observe_mixins(facts, node, consumer, callbacks)
+      graph = facts.graph
+      instance, = graph.ancestor_names(node.name)
+      singleton, = graph.ancestor_names(node.name, scope: :class)
+      candidates = callbacks.flat_map { |callback| callback.mixins.map { |mixin| [callback, mixin] } }
+      candidates.group_by { |_, mixin| [mixin.kind, mixin.target] }.each_with_object(Set.new) do |((kind, target), sites), ambiguous|
+        module_object = runtime_constant(target)
+        next unless module_object.is_a?(Module)
+
+        observed = kind == :extend ? consumer.singleton_class.include?(module_object) : consumer.include?(module_object)
+        next unless observed && !(kind == :extend ? singleton : instance).include?(target)
+        next ambiguous.merge(sites.map { |callback, _| callback.concern }) unless sites.one?
+
+        facts.mixin(owner: node, target: target, kind: kind, location: sites.first.last.location)
+      end
+    end
+
+    def observe_methods(facts, node, consumer, callbacks)
+      callbacks.flat_map(&:methods).each do |definition|
+        method = begin
+          definition.scope == :class ? consumer.method(definition.name) : consumer.instance_method(definition.name)
+        rescue NameError
+          nil
+        end
+        path, line = method&.source_location
+        next unless path && File.expand_path(path) == definition.location.path && line == definition.location.line
+
+        facts.method_definition(owner: node, definition: definition, installation: definition.location)
+      end
+    end
+
+    # Each analyzed consumer with the conditional callbacks it runs: included
+    # callbacks for an include, prepended callbacks for a prepend.
+    def consumers(graph, callbacks)
+      concerns = callbacks.map(&:concern).to_set
+      graph.constants.each_with_object({}) do |node, found|
+        next if node.namespace_only || concerns.include?(node.name) || found.key?(node.name)
+
+        applicable = callbacks.select do |callback|
+          node.mixins.fetch(callback.kind == :prepended ? :prepend : :include).include?("::#{callback.concern}")
+        end
+        found[node.name] = [node, applicable] unless applicable.empty?
+      end.values
+    end
+
+    def runtime_constant(name)
+      Object.const_get(name)
+    rescue NameError, ArgumentError
+      nil
+    end
+
+    def validator_key?(key, validator)
+      class_name = "#{key.to_s.camelize}Validator"
+      validator == class_name || validator.end_with?("::#{class_name}")
+    end
+
+    def referenced?(graph, ancestors, name)
+      graph.dependency_edges.any? { |edge| ancestors.include?(edge.from_constant) && graph.resolve_edge_constant(edge) == name }
+    end
+
+    def site_source(graph, klass, site)
+      owner = graph.constants_named(site.owner).find { |node| node.class? && node.path == site.location.path }
+      owner || source_node(graph, klass, [site])
+    end
+
+    def source_node(graph, model, candidates)
+      nodes = graph.constants_named(model.name)
+      direct = nodes.select { |node| candidates.any? { |site| site.owner == model.name && site.location.path == node.path } }
+      return direct.first if direct.one?
+
+      location = Object.const_source_location(model.name)
+      nodes.find { |node| location && node.path == File.expand_path(location.first) } || nodes.find { |node| !node.namespace_only }
+    end
+
+    # Literal association and validation declarations, found by parsing only
+    # the files that define the given classes and their analyzed ancestors.
+    def macro_sites(graph, classes)
+      names = classes.filter_map { |klass| MODULE_NAME.bind_call(klass) }.flat_map { |name| graph.ancestor_names(name).first.to_a << name }.to_set
+      paths = names.flat_map { |name| graph.constants_named(name).map(&:path) }.uniq.sort
+      owners = graph.edges.select { |edge| edge.type == :calls_named_method && paths.include?(edge.from_path) }
+                    .to_h { |edge| [[edge.from_path, edge.location], edge.from_constant] }
+      sites = []
+      paths.each { |path| collect_sites(owners, path, Prism.parse_file(path).value, sites) }
+      sites.group_by { |site| [site.macro, site.name.is_a?(String) ? site.name : :validator] }
+    end
+
+    def collect_sites(owners, path, node, sites)
+      return unless node
+      return if node.is_a?(Prism::DefNode)
+
+      if node.is_a?(Prism::CallNode) && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode))
+        location = SourceLocation.from_prism(path, node.location)
+        arguments = node.arguments&.arguments || []
+        argument = arguments.first
+        literal = argument.unescaped if argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)
+        if ASSOCIATIONS.include?(node.name)
+          sites << Site.new(node.name, literal, owners[[path, location]], location) if literal
+        elsif GENERATED_ASSOCIATIONS.key?(node.name)
+          GENERATED_ASSOCIATIONS.fetch(node.name).each do |macro, pattern|
+            sites << Site.new(macro, format(pattern, literal), owners[[path, location]], location) if literal
+          end
+        elsif VALIDATIONS.include?(node.name)
+          validation_keys(arguments).each do |key|
+            sites << Site.new(node.name, key.to_sym, owners[[path, location]], location)
+          end
+        end
+      end
+      node.compact_child_nodes.each { |child| collect_sites(owners, path, child, sites) }
+    end
+
+    def validation_keys(arguments)
+      options = arguments.select { |argument| argument.is_a?(Prism::KeywordHashNode) || argument.is_a?(Prism::HashNode) }
+      options.flat_map(&:elements).filter_map do |element|
+        key = element.key if element.is_a?(Prism::AssocNode)
+        key.unescaped if key.is_a?(Prism::SymbolNode) || key.is_a?(Prism::StringNode)
+      end
+    end
+  end
+
+  producer :rails do
+    sources 'app/models/**/*.rb', '**/app/models/**/*.rb'
+    env 'RAILS_ENV'
+    boot { |root| RailsReflector.boot(root) }
+    capture { |facts| RailsReflector.capture(facts) }
+  end
+end

data/lib/archspec/reflect_runner.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Executed only by `archspec reflect`, once per producer, in its own process.
+require_relative '../archspec'
+
+begin
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  definition, root = ArchSpec::CLI.load_definition(ENV.fetch('ARCHSPEC_REFLECTION_CONFIG'))
+  producer = ArchSpec::Producer.load(ENV.fetch('ARCHSPEC_PRODUCER'), definition)
+  document = producer.run(definition, root)
+  output = File.join(File.expand_path(definition.facts_path, root), "#{producer.name}.yml")
+  ArchSpec::Facts.write(output, document)
+  labels = { 'references' => 'reference', 'methods' => 'method', 'mixins' => 'mixin', 'gaps' => 'gap',
+             'resolves' => 'resolved gap' }
+  counts = labels.filter_map do |key, label|
+    size = key == 'methods' ? document[key].sum { |entry| entry['names'].size } : document[key].size
+    "#{size} #{label}#{'s' unless size == 1}" if size.positive?
+  end
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+  summary = counts.empty? ? 'no facts' : counts.join(', ')
+  puts format('Updated %<path>s: %<summary>s (%<seconds>.1fs)',
+    path: Pathname(output).relative_path_from(Pathname(root)), summary: summary, seconds: elapsed)
+  document['gaps'].each { |gap| puts "  gap: #{gap['path']}:#{gap['line']} #{gap['message']}" }
+rescue ArchSpec::Error => error
+  warn error.message
+  exit 1
+end

data/lib/archspec/rubydex_index.rb

@@ -131,7 +131,9 @@ module ArchSpec
             next unless syntax.constant_name_at(path, location)
 
             target, resolved = reference_target(reference, path)
-            constant.add_mixin(kind, resolved || target)
+            # A resolved name is absolute; resolving it again from the includer's
+            # scope could pick a nested constant with the same name.
+            constant.add_mixin(kind, resolved ? "::#{resolved}" : target)
             add_ancestry_edge(graph, :"#{kind}s", name, definition, reference, target, resolved)
           end
         end

data/lib/archspec/rules/concern_rules.rb

@@ -35,14 +35,14 @@ module ArchSpec
           next if consumers.empty?
 
           target = graph.resolve_edge_constant(edge)
-          next if within_namespace?(target, edge.from_constant)
-
-          includer = consumers.find { |name| within_namespace?(target, name) }
-          next unless includer
+          owner = [edge.from_constant, *consumers]
+            .select { |namespace| within_namespace?(target, namespace) }
+            .max_by(&:length)
+          next unless consumers.include?(owner)
 
           Diagnostic.new(
             rule: id,
-            message: "#{edge.from_constant} must not reference its includer #{includer}",
+            message: "#{edge.from_constant} must not reference its includer #{owner}",
             location: edge.location,
             evidence: "#{edge.from_constant} #{edge.verb} #{target}"
           )

data/lib/archspec/rules/dependency_rules.rb

@@ -42,9 +42,10 @@ module ArchSpec
 
       def evaluate(graph)
         relevant_edges(graph).flat_map do |edge|
-          graph.target_components_for(edge).filter_map do |target|
-            next if target == source || targets.include?(target)
+          owners = graph.target_components_for(edge)
+          next [] if owners.any? { |target| target == source || targets.include?(target) }
 
+          owners.map do |target|
             Diagnostic.new(
               rule: id,
               message: "#{source} may not depend on #{target}",
@@ -107,9 +108,8 @@ module ArchSpec
         graph.dependency_edges.flat_map do |edge|
           next [] unless graph.target_components_for(edge).include?(source)
 
-          offenders = graph.source_components_for(edge).reject do |component|
-            component == source || consumers.include?(component)
-          end
+          offenders = graph.source_components_for(edge)
+          next [] if offenders.any? { |component| component == source || consumers.include?(component) }
 
           offenders.map do |offender|
             Diagnostic.new(

data/lib/archspec/rules/protocol_rules.rb

@@ -74,7 +74,8 @@ module ArchSpec
       def own_method_call?(graph, edge)
         return false unless edge.receiver == :none && edge.from_constant
 
-        methods, = graph.effective_instance_methods(edge.from_constant)
+        owner = edge.resolved_receiver || edge.from_constant
+        methods, = graph.effective_methods(owner, edge.receiver_scope || :instance)
         methods.include?(edge.to.to_sym)
       end
     end

data/lib/archspec/sources/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'comment'
+
+module ArchSpec
+  module Sources
+    # Shared interface for source adapters. Normalizes the file path, parses
+    # eagerly, and converts parser errors to ArchSpec source locations.
+    # Subclasses provide supported extensions, a Prism program, and comments.
+    class Base
+      def self.extensions
+        raise NotImplementedError
+      end
+
+      def self.rubydex_indexable?
+        false
+      end
+
+      attr_reader :path
+
+      def initialize(path)
+        @path = File.expand_path(path)
+        @result = parse_file
+      end
+
+      def comments
+        raise NotImplementedError
+      end
+
+      def prism
+        raise NotImplementedError
+      end
+
+      def parse_errors
+        result.errors.map do |error|
+          ParseError.new(error.message, SourceLocation.from_prism(path, error.location))
+        end
+      end
+
+      private
+
+      attr_reader :result
+
+      def parse_file
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/archspec/sources/comment.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Sources
+    # Parser-independent comment text and position for suppression handling.
+    # Lines are one-based and columns are zero-based byte offsets within a line.
+    Comment = Data.define(:text, :line, :column) do
+      def self.from_prism(comment)
+        location = comment.location
+        new(comment.slice, location.start_line, location.start_column)
+      end
+    end
+  end
+end

data/lib/archspec/sources/erb.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'herb'
+require 'prism'
+require_relative 'base'
+
+module ArchSpec
+  module Sources
+    # Parses ERB templates with Herb, exposing a complete Prism program and
+    # suppression comments at their original template positions. ERB sources
+    # contribute syntax facts without being indexed by Rubydex.
+    class Erb < Base
+      attr_reader :comments, :prism
+
+      def self.extensions
+        %w[.erb]
+      end
+
+      private
+
+      def parse_file
+        source = File.read(path)
+        document = Herb.parse(source, prism_program: true).value
+        # Herb omits the program payload for a completely empty file.
+        parsed = source.empty? ? Prism.parse('', filepath: path) : Prism.load(source, document.prism_node)
+        @prism = parsed.value
+        collect_comments!(source, document, parsed)
+        parsed
+      end
+
+      def collect_comments!(source, document, parsed)
+        bytes = source.b
+        @comments = []
+        # Work around a Herb bug: Prism comment ranges extend past ERB closing
+        # tags to the end of the physical line. This Collects tag boundaries and
+        # clamps comments; Intention is to remove once it's fixed upstream.
+        ruby_ranges = []
+        collect_erb_comments(document, bytes, ruby_ranges)
+        ruby_ranges.sort_by!(&:from)
+        parsed.comments.each do |comment|
+          location = comment.location
+          range = ruby_ranges.bsearch { |candidate| candidate.to > location.start_offset }
+          finish = location.end_offset
+          finish = [finish, range.to].min if range && range.from <= location.start_offset
+          @comments << Comment.new(source.byteslice(location.start_offset...finish), location.start_line, location.start_column)
+        end
+        @comments.uniq! { |comment| [comment.line, comment.column] }
+      end
+
+      def collect_erb_comments(node, bytes, ruby_ranges)
+        if node.is_a?(Herb::AST::ERBCommentNode)
+          process_erb_comment(node.content, bytes)
+        elsif node.respond_to?(:tag_opening) && node.tag_opening&.value&.start_with?('<%') &&
+              node.respond_to?(:content) && node.content
+          ruby_ranges << node.content.range
+          # Work around a Herb bug: single-line comment-only Ruby tags are absent
+          # from the Prism comments. This recovers them from the AST, excluding escapes.
+          # Intention is to remove this once the bug is fixed upstream in Herb.
+          if node.is_a?(Herb::AST::ERBContentNode) && %w[<% <%-].include?(node.tag_opening.value) &&
+             node.content.value.match?(/\A[^\S\r\n]*#[^\r\n]*\z/)
+            token = node.content
+            offset = token.range.from + token.value.b.index('#')
+            @comments << Comment.new(token.value.lstrip, token.location.start.line, byte_column(bytes, offset))
+          end
+        end
+
+        node.compact_child_nodes.each do |child|
+          collect_erb_comments(child, bytes, ruby_ranges)
+        end
+      end
+
+      def process_erb_comment(token, bytes)
+        start = token.location.start
+        column = byte_column(bytes, token.range.from)
+        token.value.each_line.with_index do |text, index|
+          @comments << Comment.new(text, start.line + index, index.zero? ? column : 0)
+        end
+      end
+
+      def byte_column(bytes, offset)
+        line_start = (bytes.rindex("\n", offset - 1) || -1) + 1
+        offset - line_start
+      end
+    end
+  end
+end

data/lib/archspec/sources/ruby.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'prism'
+require_relative 'base'
+
+module ArchSpec
+  module Sources
+    # Parses Ruby and Rake files with Prism and exposes their program and
+    # comments. These sources also support semantic indexing with Rubydex.
+    class Ruby < Base
+      def self.extensions
+        %w[.rb .rake]
+      end
+
+      def self.rubydex_indexable?
+        true
+      end
+
+      def comments
+        result.comments.map { |comment| Comment.from_prism(comment) }
+      end
+
+      def prism
+        result.value
+      end
+
+      private
+
+      def parse_file
+        Prism.parse_file(path)
+      end
+    end
+  end
+end

data/lib/archspec/todo.rb

@@ -8,8 +8,12 @@ module ArchSpec
   # in an existing app and burn the list down over time. Matched by
   # ArchSpec::Diagnostic#fingerprint, so entries survive edits that shift lines.
   class Todo
+    # The keys an entry keeps. Anything else in the file, such as the line an
+    # older format recorded, is dropped so reports have one fixed shape.
+    FIELDS = %w[id rule path message evidence].freeze
+
     def self.empty(root: nil)
-      new(Set.new, root: root)
+      new({}, root: root)
     end
 
     def self.load(path, root:)
@@ -20,16 +24,17 @@ module ArchSpec
         raise Error, "invalid todo file #{path}: expected a violations list"
       end
 
-      ids = Array(document['violations']).map.with_index do |entry, index|
+      entries = Array(document['violations']).each_with_index.to_h do |entry, index|
         id = entry.is_a?(Hash) ? entry['id'] : entry
         unless id.is_a?(String) && !id.empty?
           raise Error, "invalid todo file #{path}: violation #{index + 1} has no id"
         end
 
-        id
+        fields = entry.is_a?(Hash) ? entry : {}
+        [id, FIELDS.to_h { |key| [key, fields[key]] }.merge('id' => id)]
       end
 
-      new(ids.to_set, root: root)
+      new(entries, root: root)
     rescue Error
       raise
     rescue Psych::Exception, SystemCallError => e
@@ -37,34 +42,40 @@ module ArchSpec
     end
 
     def self.write(path, diagnostics, root:)
-      payload = {
-        'violations' => diagnostics.map do |diagnostic|
-          {
-            'id' => diagnostic.fingerprint(root: root),
-            'rule' => diagnostic.rule,
-            'path' => diagnostic.location.relative_path(root),
-            'line' => diagnostic.location.line,
-            'message' => diagnostic.message
-          }
-        end
-      }
+      entries = diagnostics.map do |diagnostic|
+        {
+          'id' => diagnostic.fingerprint(root: root),
+          'rule' => diagnostic.rule,
+          'path' => diagnostic.location.relative_path(root),
+          'message' => diagnostic.message,
+          'evidence' => diagnostic.evidence
+        }
+      end
+      entries.uniq! { |entry| entry['id'] }
+      entries.sort_by! { |entry| entry.values_at('path', 'rule', 'message', 'evidence') }
 
-      File.write(path, payload.to_yaml)
+      File.write(path, { 'violations' => entries }.to_yaml)
+      entries.size
     rescue SystemCallError => e
       raise Error, "could not write todo file #{path}: #{e.message}"
     end
 
-    def initialize(ids, root:)
-      @ids = ids
+    def initialize(entries, root:)
+      @entries = entries
       @root = root
     end
 
     def include?(diagnostic)
-      ids.include?(diagnostic.fingerprint(root: root))
+      entries.key?(diagnostic.fingerprint(root: root))
+    end
+
+    def unmatched_by(diagnostics)
+      matched = diagnostics.map { |diagnostic| diagnostic.fingerprint(root: root) }.to_set
+      entries.reject { |id, _entry| matched.include?(id) }.values
     end
 
     private
 
-    attr_reader :ids, :root
+    attr_reader :entries, :root
   end
 end

data/lib/archspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArchSpec
-  VERSION = '1.1.0.rc2'
+  VERSION = '1.2.0'
 end