pinspec 0.2.0 → 0.3.0

data/lib/pinspec/analyzer/target_parser.rb

@@ -19,13 +19,26 @@ module Pinspec
 
       VISIBILITIES = %i[public private protected].freeze
 
-      SCALARISH_NAMES = %w[
-        amount total subtotal price cost quantity qty count index number num
-        name email phone title body text message description reason code type
-        kind status state value key data payload options opts args params attrs
-        attributes config settings id token flag mode format scope limit offset
-        date time now today percent rate ratio sum size length label url path
-      ].freeze
+      # Names that are a bag of attributes rather than a model. `create_params`,
+      # `options`, `article_attributes`.
+      HASH_SHAPED = /\A(?:\w+_)?(?:params|options|attributes|attrs|opts)\z/
+
+      # These names are not models - but saying only that leaves the corpus with no
+      # value at all, and a required parameter then receives an invented nil. The
+      # target raises on it and pinspec pins that error as the application's
+      # behaviour, which is the one thing it promises never to do. So each name maps
+      # to a type the corpus can actually build.
+      SCALARISH_TYPES = {
+        "String" => %w[
+          name email phone title body text message description reason code key
+          path url slug token label format mode scope type kind status state
+          value data
+        ],
+        "Integer" => %w[count index number num limit offset size length quantity qty position],
+        "Float" => %w[amount total subtotal price cost percent rate ratio sum]
+      }.freeze
+
+      SCALARISH_NAMES = SCALARISH_TYPES.values.flatten.freeze
 
       DI_PATTERNS = [
         /\ARails\.application\.config\b/,
@@ -60,8 +73,9 @@ module Pinspec
           new(file_path, method_name).parse
         end
 
-        DEFAULT_METHOD = "call"
-
+        # Returns [file, method] with method nil when the target named none. It is
+        # the caller's job to discover one, because that needs the file's contents
+        # and the surrounding directory's convention.
         def split_target(target)
           text = target.to_s
           return text.split("#", 2) if text.include?("#")
@@ -72,11 +86,35 @@ module Pinspec
                   "(got #{target.inspect}); e.g. app/services/invoice_calculator.rb#call"
           end
 
-          [text, DEFAULT_METHOD]
+          [text, nil]
         end
       end
 
-      def initialize(file_path, method_name)
+      class << self
+        # Keyed by application root, because a batch run builds one parser per file
+        # and re-globbing the application for each would be quadratic.
+        def application_sources_for(root)
+          @application_sources ||= {}
+          @application_sources[root] ||= begin
+            dirs = %w[app lib].map { |d| File.join(root, d) }.select { |d| File.directory?(d) }
+            dirs.flat_map { |dir| Dir.glob(File.join(dir, "**", "*.rb")) }.sort
+          end
+        end
+
+        def application_scope_cache(root)
+          @application_scopes ||= {}
+          @application_scopes[root] ||= {}
+        end
+
+        # Tests and long-lived processes need a way back to a clean slate.
+        def reset_application_cache!
+          @application_sources = {}
+          @application_scopes = {}
+        end
+      end
+
+      def initialize(file_path, method_name, app_root: nil)
+        @app_root   = app_root
         @file_path  = file_path
         @descriptor = parse_descriptor(method_name)
       end
@@ -113,7 +151,8 @@ module Pinspec
           takes_block:          false,
           source_range:         [mdef.node.location.start_line, mdef.node.location.end_line],
           referenced_constants: referenced_constants(scan),
-          clock_sites:          clock_sites(scan)
+          clock_sites:          clock_sites(scan),
+          construction_source:  @construction_source || :own
         )
       end
 
@@ -392,8 +431,12 @@ module Pinspec
 
       def resolve_construction(scope, mdef)
         return [:class_method, []] if mdef.singleton
+        return [:class_method, []] if module_self_calling?(scope)
         return [:model_instance, []] if model_scope?(scope)
 
+        attr_extras = attr_extras_params(scope)
+        return [:new, attr_extras] if attr_extras
+
         members = struct_members(scope)
         return [:struct, members] if members
 
@@ -409,33 +452,60 @@ module Pinspec
         inherited_construction(scope)
       end
 
+      # A class with no #initialize is not an unreadable constructor - it is the
+      # default one. The commonest shape in real applications is a service that
+      # inherits behaviour and takes its dependencies as method arguments:
+      #
+      #   class FavouriteService < BaseService
+      #     def call(account, status)
+      #
+      # Refusing that cost 88% of one real codebase's service directory. So the
+      # superclass chain is followed through the application, and only a constructor
+      # that EXISTS and cannot be read is refused.
+      MAX_ANCESTOR_HOPS = 4
+
       def inherited_construction(scope)
         sup = scope.superclass_slice
         return [:new, []] if sup.nil? || INERT_BASES.include?(sup)
 
-        parent = resolve_scope_relative(sup, scope)
-        unless parent
-          raise UnresolvableSetup.new(
-            :opaque_constructor,
-            "#{scope.name} inherits from #{sup}, which is not defined in " \
-            "#{@file_path}, and defines no #initialize of its own, so its " \
-            "constructor signature can't be read statically. Give #{scope.name} " \
-            "an explicit #initialize, or pin a class-method entry point."
-          )
-        end
+        params = ancestor_initializer_params(sup, scope)
+        return params if params
 
-        parent_init = find_initialize(parent.name)
-        return [:new, params_of(parent_init)] if parent_init
+        # Nothing in the chain defines one, so `new` takes no arguments. When the
+        # chain left the application the assumption is unverified, and says so.
+        @construction_source = @left_application ? :assumed : :inherited
+        [:new, []]
+      end
 
-        parent_sup = parent.superclass_slice
-        return [:new, []] if parent_sup.nil? || INERT_BASES.include?(parent_sup)
+      # Walks up through the application. Returns [:new, params] when an ancestor
+      # defines #initialize, or nil when none does.
+      def ancestor_initializer_params(name, scope)
+        seen = []
+        current = name
+        hops = 0
 
-        raise UnresolvableSetup.new(
-          :opaque_constructor,
-          "#{scope.name} < #{parent.name} < #{parent_sup}: neither #{scope.name} " \
-          "nor #{parent.name} defines #initialize, and #{parent_sup} is outside " \
-          "#{@file_path}. pinspec resolves one level up only."
-        )
+        while current && hops < MAX_ANCESTOR_HOPS
+          break if INERT_BASES.include?(current) || seen.include?(current)
+
+          seen << current
+          hops += 1
+
+          parent = resolve_scope_relative(current, scope) || scope_from_application(current)
+          if parent.nil?
+            @left_application = true
+            return nil
+          end
+
+          init = find_initialize(parent.name) || initializer_in(parent)
+          if init
+            @construction_source = :inherited
+            return [:new, params_of(init)]
+          end
+
+          current = parent.superclass_slice
+        end
+
+        nil
       end
 
       def guard_opaque_initialize!(scope, init)
@@ -490,6 +560,62 @@ module Pinspec
         MODEL_BASES.include?(sup) || MODEL_BASES.any? { |b| sup.end_with?("::#{b}") }
       end
 
+      # A module that calls `module_function` or `extend self` answers its own methods,
+      # so there is nothing to construct. Calling .new on it raised
+      # "undefined method 'new' for module ..." inside the probe - a setup_error that
+      # named the application rather than the shape pinspec had failed to recognise.
+      def module_self_calling?(scope)
+        return false unless scope.kind == :module
+
+        scope_calls(scope).any? do |call|
+          call.receiver.nil? && %i[module_function extend].include?(call.name) &&
+            (call.name == :module_function || self_argument?(call))
+        end
+      end
+
+      def self_argument?(call)
+        Array(call.arguments&.arguments).any? { |arg| arg.is_a?(Prism::SelfNode) }
+      end
+
+      # attr_extras. `pattr_initialize`/`attr_initialize` generate the constructor, so
+      # a class using one has no `def initialize` to read and looked like it took no
+      # arguments at all - pinspec then called .new with nothing and the generated
+      # constructor raised KeyError. That is 110 of chatwoot's 386 service files.
+      #
+      #   pattr_initialize :account, :params          -> two required positionals
+      #   pattr_initialize [:inbox!, :params!]        -> two required keywords
+      #   pattr_initialize [:channel!, :message]      -> one required, one optional
+      #
+      # A bare symbol is positional; symbols inside an array are keywords, and the
+      # trailing "!" is attr_extras' own mark for "required".
+      ATTR_EXTRAS_MACROS = %i[pattr_initialize attr_initialize].freeze
+
+      def attr_extras_params(scope)
+        call = scope_calls(scope).find do |node|
+          node.receiver.nil? && ATTR_EXTRAS_MACROS.include?(node.name)
+        end
+        return nil if call.nil?
+
+        Array(call.arguments&.arguments).flat_map { |arg| attr_extras_args(arg) }
+      end
+
+      def attr_extras_args(node)
+        case node
+        when Prism::SymbolNode
+          [build_param(node.unescaped.to_sym, :req, nil)]
+        when Prism::ArrayNode
+          node.elements.grep(Prism::SymbolNode).map do |element|
+            name = element.unescaped
+            required = name.end_with?("!")
+
+            build_param(name.delete_suffix("!").to_sym, required ? :keyreq : :key,
+                        required ? nil : "nil")
+          end
+        else
+          []
+        end
+      end
+
       def struct_members(scope)
         node = scope.superclass_node
         return nil unless node.is_a?(Prism::CallNode)
@@ -560,6 +686,110 @@ module Pinspec
         end&.node
       end
 
+      # The superclass usually lives in another file of the same application. Finding
+      # it is a search for `class <Name>` under app/ and lib/, parsed with Prism so a
+      # name inside a comment or a string cannot match.
+      def scope_from_application(name)
+        return nil if application_root.nil?
+
+        cache = self.class.application_scope_cache(application_root)
+        return cache[name] if cache.key?(name)
+
+        cache[name] = find_scope_in_application(name)
+      end
+
+      def find_scope_in_application(name)
+        demodulized = name.split("::").last
+        pattern = /^\s*class\s+(?:[\w:]+::)?#{Regexp.escape(demodulized)}\b/
+
+        application_sources.each do |path|
+          source = Source.read(path)
+          next unless source.match?(pattern)
+
+          result = Prism.parse(source)
+          next unless result.success?
+
+          found = scope_named(result.value, name, demodulized)
+          return found if found
+        end
+
+        nil
+      end
+
+      # Only the files an application owns. A gem's base class is deliberately out of
+      # reach: pinspec would be reading code the application cannot change.
+      def application_sources
+        self.class.application_sources_for(application_root)
+      end
+
+      def application_root
+        return @application_root if defined?(@application_root)
+
+        @application_root = @app_root || infer_application_root
+      end
+
+      # Walk up from the target until something that marks a Rails root appears.
+      def infer_application_root
+        dir = File.dirname(File.expand_path(@file_path))
+
+        while dir != "/" && dir != File.dirname(dir)
+          return dir if File.file?(File.join(dir, "Gemfile")) ||
+                        File.directory?(File.join(dir, "db")) ||
+                        File.file?(File.join(dir, "config", "application.rb"))
+
+          dir = File.dirname(dir)
+        end
+
+        nil
+      end
+
+      def scope_named(root, qualified, demodulized)
+        found = nil
+
+        walk = lambda do |node, prefix|
+          return if found || node.nil?
+
+          if node.is_a?(Prism::ClassNode)
+            name = [prefix, node.constant_path.slice].compact.reject(&:empty?).join("::")
+            if name == qualified || node.constant_path.slice == qualified ||
+               node.constant_path.slice == demodulized
+              found = Scope.new(name: name, node: node, kind: :class,
+                                superclass_slice: node.superclass&.slice,
+                                superclass_node: node.superclass, parent: nil)
+              return
+            end
+            prefix = name
+          elsif node.is_a?(Prism::ModuleNode)
+            prefix = [prefix, node.constant_path.slice].compact.reject(&:empty?).join("::")
+          end
+
+          node.compact_child_nodes.each { |child| walk.call(child, prefix) }
+        end
+
+        walk.call(root, nil)
+        found
+      end
+
+      # An #initialize defined directly in a scope found elsewhere in the application.
+      def initializer_in(scope)
+        return nil unless scope.node.is_a?(Prism::ClassNode)
+
+        found = nil
+        walk = lambda do |node|
+          return if found || node.nil?
+
+          if node.is_a?(Prism::DefNode) && node.name == :initialize && node.receiver.nil?
+            found = node
+            return
+          end
+
+          node.compact_child_nodes.each { |child| walk.call(child) }
+        end
+
+        walk.call(scope.node.body)
+        found
+      end
+
       def resolve_scope_relative(name, scope)
         nesting = scope.name.split("::")
 
@@ -634,7 +864,10 @@ module Pinspec
         return "Array"   if s.end_with?("_ids")
         return "Time"    if s.end_with?("_at")
         return "Date"    if s.end_with?("_on", "_date")
-        return nil if SCALARISH_NAMES.include?(s)
+        return "Hash"    if HASH_SHAPED.match?(s)
+        return "Array"   if s.end_with?("s") && !s.end_with?("ss", "us", "is")
+        scalar = SCALARISH_TYPES.find { |_type, names| names.include?(s) }
+        return scalar.first if scalar
         return nil unless s.match?(/\A[a-z][a-z0-9_]*\z/)
 
         camelize(s)

data/lib/pinspec/cli.rb

@@ -11,7 +11,7 @@ module Pinspec
       true
     end
 
-    ORDER = %w[pin init analyze validate report plan capture version].freeze
+    ORDER = %w[pin verify init analyze validate report plan capture version].freeze
 
     # Thor sorts the command list alphabetically after building it, which buries the
     # one verb most people want between `init` and `plan`, and gives the two
@@ -30,6 +30,32 @@ module Pinspec
     end
     map %w[--version -v] => :version
 
+    desc "verify SPEC_FILE", "Run any spec file in pinspec's environments, whoever wrote it"
+    method_option :app, type: :string, default: ".", desc: "target app root"
+    method_option :"verify-level", type: :string, default: "full", enum: %w[full isolated]
+    method_option :"app-env", type: :string, repeatable: true, banner: "KEY=VALUE",
+                              desc: "environment for the app's own runtime"
+    def verify(*args)
+      guarded do
+        spec_file = target_from(args)
+        path = File.expand_path(spec_file, options[:app])
+
+        unless File.file?(path)
+          raise TargetNotFound, "no spec file at #{path}"
+        end
+
+        outcomes = Verify::Verifier.new(
+          app_root: options[:app], spec_path: path, env: app_env,
+          level: setting("verify-level", "full").to_sym
+        ).verify
+
+        puts "verify   #{spec_file}"
+        print_verification(outcomes)
+
+        raise VerifyFailed, verify_failed_message(outcomes) unless outcomes.all?(&:green?)
+      end
+    end
+
     desc "init [APP_PATH]", "Write .pinspec.yml so later runs need no flags"
     method_option :force, type: :boolean, default: false, desc: "overwrite an existing .pinspec.yml"
     def init(app_path = ".")
@@ -71,9 +97,11 @@ module Pinspec
     method_option :app, type: :string, default: ".", desc: "target app root"
     method_option :cases, type: :numeric, default: Inputs::Corpus::DEFAULT_MAX_CASES,
                           desc: "max input cases per method"
+    method_option :method, type: :string, banner: "NAME",
+                          desc: "the method to pin, when discovery would guess or refuse"
     def plan(target)
       guarded do
-        file, method = Analyzer::TargetParser.split_target(target)
+        file, method = resolve_target(target)
         target_profile = Analyzer::TargetParser.parse(file, method)
 
         print_profile(target_profile)
@@ -116,6 +144,8 @@ module Pinspec
                           desc: "probe boots; 2 is the default because one process shares warm caches"
     method_option :"compare-sql", type: :boolean, default: false,
                                   desc: "include SQL fingerprints in the stability decision"
+    method_option :method, type: :string, banner: "NAME",
+                          desc: "the method to pin, when discovery would guess or refuse"
     method_option :"app-env", type: :string, repeatable: true, banner: "KEY=VALUE",
                               desc: "environment for the app's own runtime (when it is not this shell's Ruby)"
     method_option :sample, type: :boolean, default: false,
@@ -125,7 +155,7 @@ module Pinspec
     def capture(*args)
       guarded do
         target = target_from(args)
-        file, method = Analyzer::TargetParser.split_target(target)
+        file, method = resolve_target(target)
 
         result = Runner::Capture.new(
           app_root:    options[:app],
@@ -153,18 +183,19 @@ module Pinspec
     method_option :"skip-verify", type: :boolean, default: false
     method_option :force, type: :boolean, default: false,
                          desc: "overwrite a pin file that has been hand-edited"
-    method_option :snapshot, type: :string, default: "inline", enum: %w[inline insta approvals],
-                             desc: "snapshot backend"
+    method_option :method, type: :string, banner: "NAME",
+                          desc: "the method to pin, when discovery would guess or refuse"
     method_option :"app-env", type: :string, repeatable: true, banner: "KEY=VALUE",
                               desc: "environment for the app's own runtime (when it is not this shell's Ruby)"
     method_option :sample, type: :boolean, default: false,
                            desc: "read real rows through a generated read-only script in the app"
     method_option :"no-redact", type: :boolean, default: false,
                                desc: "do NOT rewrite personal data in sampled rows (they land in a committed file)"
+    method_option :snapshot, type: :string, hide: true
     def pin(*args)
       guarded do
         target = target_from(args)
-        refuse_unbuilt_backend!
+        warn_about_retired_flags!
         warn_about_redaction!
 
         return pin_directory(target) if File.directory?(target)
@@ -178,7 +209,12 @@ module Pinspec
         files = Batch.targets_in(path)
         raise TargetNotFound, "no .rb files under #{path}" if files.empty?
 
-        puts "pinning #{files.size} file(s) under #{path}"
+        # Counted once over the directory: the method name this application uses for
+        # its entry points. chatwoot says `perform`, mastodon says `call`.
+        @convention = Analyzer::Discovery.convention_for(files)
+
+        puts "pinning #{files.size} file(s) under #{path}" \
+             "#{@convention ? " (this app's convention: ##{@convention})" : ''}"
         puts
 
         report = Batch.new(files) { |file| pin_one(file, quiet: true) }.run
@@ -190,13 +226,13 @@ module Pinspec
       end
 
       def pin_one(target, quiet: false)
-        file, method = Analyzer::TargetParser.split_target(target)
+        file, method = resolve_target(target)
 
         capture = Runner::Capture.new(
           app_root: options[:app], target: file, method: method,
           max_cases: setting('cases', Inputs::Corpus::DEFAULT_MAX_CASES),
           boots: setting('boots', 2), sandbox_env: app_env,
-          sample: setting('sample', false), redact: !options[:"no-redact"]
+          sample: setting('sample', false), redact: !options[:"no-redact"] && setting("redact", true)
         ).run
 
         print_capture(capture) unless quiet
@@ -255,12 +291,14 @@ module Pinspec
     method_option :cases, type: :numeric, default: Inputs::Corpus::DEFAULT_MAX_CASES
     method_option :"test-command", type: :string,
                                    desc: "run the app's suite in its own runtime (for apps on Ruby < 3.4)"
+    method_option :method, type: :string, banner: "NAME",
+                          desc: "the method to pin, when discovery would guess or refuse"
     method_option :"app-env", type: :string, repeatable: true, banner: "KEY=VALUE",
                               desc: "environment for the app's own runtime"
     def validate(*args)
       guarded do
         target = target_from(args)
-        file, method = Analyzer::TargetParser.split_target(target)
+        file, method = resolve_target(target)
 
         capture = Runner::Capture.new(
           app_root: options[:app], target: file, method: method,
@@ -322,9 +360,7 @@ module Pinspec
       @legacy_env = pairs
 
       if targets.empty?
-        raise TargetNotFound,
-              "no target given. Pass a file, a FILE#METHOD, or a directory: " \
-              "pinspec pin app/services/invoice_calculator.rb"
+        raise TargetNotFound, no_target_message
       end
 
       if targets.size > 1
@@ -342,6 +378,90 @@ module Pinspec
            "Prefer `--app-env A=1 --app-env B=2`, or record it once with `pinspec init`."
     end
 
+    # `pinspec pin app/services/foo.rb` used to assume #call. Across five public Rails
+    # codebases only 14% of service files had a resolvable one - chatwoot's are named
+    # `perform` - so the method is discovered instead, using the convention the
+    # application itself follows.
+    def resolve_target(target)
+      file, method = Analyzer::TargetParser.split_target(target)
+
+      unless File.file?(file) || File.directory?(file)
+        raise TargetNotFound,
+              "no file at #{file}. Pass a path to a Ruby file, a FILE#METHOD, or a " \
+              "directory - paths are relative to where you are, not to --app."
+      end
+
+      return [file, method] if method
+      return [file, options[:method]] if options[:method]
+
+      choice = Analyzer::Discovery.new(file).choose(convention: @convention)
+
+      if choice.ambiguous?
+        raise AmbiguousTarget, ambiguous_message(file, choice)
+      end
+
+      @chosen = choice
+      [file, existing_pin_method(file, choice) || choice.descriptor]
+    end
+
+    # Discovery follows the application's convention, which can differ from what an
+    # older pinspec chose - it always assumed #call. Re-pinning a class under a new
+    # method would leave the previous pin sitting in the suite, unmaintained and still
+    # running. So an existing pin for this class decides.
+    def existing_pin_method(file, choice)
+      dir = File.join(options[:app], Emit::SpecWriter::SPEC_DIR)
+      return nil unless File.directory?(dir)
+
+      profile = Analyzer::TargetParser.parse(file, choice.descriptor)
+      stem = Emit::SpecWriter.class_stem(profile.class_name)
+
+      # A pin's filename cannot carry `?` or `!`, so compare on the same stripped
+      # form the filename uses - otherwise a pinned `#valid?` reads back as `valid`,
+      # which is not a method the class has.
+      stripped = ->(name) { name.to_s.gsub(/[^a-z0-9_]/i, "") }
+      pinned = Dir.glob(File.join(dir, "#{stem}_*_spec.rb"))
+                  .map { |path| File.basename(path).delete_prefix("#{stem}_").delete_suffix("_spec.rb") }
+                  .reject { |name| name == stripped.call(choice.method_name) }
+
+      return nil unless pinned.size == 1
+
+      # Resolve the stem back to the method the class really defines, so `?` and `!`
+      # survive the round trip.
+      surface = Analyzer::Discovery.new(file).surface
+      real = (surface[:instance] + surface[:singleton]).find { |name| stripped.call(name) == pinned.first }
+      return nil if real.nil?
+
+      warn "pinspec: keeping ##{real}, which this class is already pinned on. " \
+           "Discovery would have chosen ##{choice.method_name}; pass " \
+           "#{File.basename(file)}##{choice.method_name} to switch."
+      real
+    rescue StandardError
+      nil
+    end
+
+    # --skip-verify means nothing was verified, so the summary must not say it was.
+    def no_target_message
+      return "no spec file given: pinspec verify spec/models/order_spec.rb" if current_command_chain.first == :verify
+
+      "no target given. Pass a file, a FILE#METHOD, or a directory: " \
+        "pinspec pin app/services/invoice_calculator.rb"
+    end
+
+    def verified_word
+      options[:"skip-verify"] ? "not verified" : "verified"
+    end
+
+    def ambiguous_message(file, choice)
+      if choice.reason == :no_public_methods
+        "#{File.basename(file)} defines no public method to pin. Name one explicitly " \
+          "if it is private on purpose: #{File.basename(file)}#the_method"
+      else
+        "#{File.basename(file)} defines several public methods and none is a " \
+          "conventional entry point (#{choice.candidates.join(', ')}). Name the one " \
+          "you mean: #{File.basename(file)}##{choice.candidates.first}"
+      end
+    end
+
     def config
       @config ||= Config.load(options[:app] || ".")
     end
@@ -362,14 +482,14 @@ module Pinspec
       config.value(key, options[key.to_sym], default)
     end
 
-    def refuse_unbuilt_backend!
-      backend = options[:snapshot]
-      return if backend.nil? || backend == "inline"
+    # `--snapshot` selected a backend whose only implementation refused two of its
+    # three values. It is accepted and ignored so that upgrading does not break a
+    # script that passed it.
+    def warn_about_retired_flags!
+      return if options[:snapshot].nil?
 
-      raise VerifyFailed,
-            "the #{backend} snapshot backend is not built yet; only `inline` is. " \
-            "Inline snapshots keep the pinned value in the spec file, where a reviewer " \
-            "can read it - which is why it is the default. Re-run without --snapshot."
+      warn "pinspec: --snapshot was removed and is ignored. A pin has always been " \
+           "inline literals, which is what that flag selected by default."
     end
 
     def warn_about_redaction!
@@ -405,7 +525,7 @@ module Pinspec
       return if graph.skipped_statements.empty?
 
       puts
-      puts "  hazards (relevance is decided once a plan exists, in M-05):"
+      puts "  hazards - statements pinspec could not read; relevant only if a plan needs these tables:"
       graph.skipped_statements.each { |statement| puts "    #{statement}" }
     end
 
@@ -736,7 +856,8 @@ module Pinspec
         name = File.basename(outcome.file).ljust(width)
 
         puts case outcome.status
-             when :pinned  then format("  pinned   %s  %d case(s), verified", name, outcome.pinned)
+             when :pinned  then format("  pinned   %s  %-10s %d case(s), #{verified_word}",
+                                       name, "##{outcome.target.to_s[/#(.+)\z/, 1]}", outcome.pinned)
              when :refused then format("  skipped  %s  %s", name, outcome.detail)
              else               format("  FAILED   %s  %s", name, outcome.detail)
              end

data/lib/pinspec/config.rb

@@ -6,7 +6,11 @@ module Pinspec
   class Config
     FILENAME = ".pinspec.yml"
 
-    KEYS = %w[cases boots sample redact compare-sql verify-level snapshot test-command env].freeze
+    KEYS = %w[cases boots sample redact compare-sql verify-level test-command env].freeze
+
+    # Keys that used to be valid. A config written for an older pinspec is ignored
+    # with a note rather than failing the run - an upgrade should not stop a build.
+    RETIRED_KEYS = %w[snapshot].freeze
 
     EMPTY = { "env" => {} }.freeze
 
@@ -17,7 +21,14 @@ module Pinspec
       parsed = YAML.safe_load(Analyzer::Source.read(path), permitted_classes: [], aliases: false) || {}
       raise ConfigInvalid, "#{path} must contain a mapping, got #{parsed.class}" unless parsed.is_a?(Hash)
 
-      unknown = parsed.keys.map(&:to_s) - KEYS
+      retired = parsed.keys.map(&:to_s) & RETIRED_KEYS
+      unless retired.empty?
+        warn "pinspec: #{path} sets #{retired.map(&:inspect).join(', ')}, which " \
+             "#{retired.size == 1 ? 'was' : 'were'} removed. Ignoring #{retired.size == 1 ? 'it' : 'them'}; " \
+             "delete the line to silence this."
+      end
+
+      unknown = parsed.keys.map(&:to_s) - KEYS - RETIRED_KEYS
       unless unknown.empty?
         raise ConfigInvalid,
               "#{path} has unknown #{unknown.size == 1 ? 'key' : 'keys'} " \