pinspec 0.1.0 → 0.3.0

data/lib/pinspec/cli.rb

@@ -4,10 +4,25 @@ require "thor"
 
 module Pinspec
   class CLI < Thor
+    class_option :verbose, type: :boolean, default: false, aliases: "-V",
+                           desc: "show the plan id, compared fields and per-case detail"
+
     def self.exit_on_failure?
       true
     end
 
+    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
+    # diagnostics equal billing with the product.
+    def self.sort_commands!(list)
+      list.sort_by! do |usage, _|
+        name = usage.to_s.split(/\s+/)[1].to_s
+        [ORDER.index(name) || ORDER.size, name]
+      end
+    end
+
     desc "version", "Print the pinspec version"
     def version
       puts "pinspec #{Pinspec::VERSION} " \
@@ -15,13 +30,78 @@ module Pinspec
     end
     map %w[--version -v] => :version
 
-    desc "plan FILE#METHOD", "Resolve a target and print the SetupPlan that would build its world"
+    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 = ".")
+      guarded do
+        path = File.join(app_path, Config::FILENAME)
+
+        if File.file?(path) && !options[:force]
+          raise ConfigInvalid, "#{path} already exists. Pass --force to overwrite it."
+        end
+
+        runtime = Runner::Runtime.for(app_path)
+        profile = Analyzer::AppProfileReader.read(app_path)
+
+        # Deliberately NOT the detected environment. Writing the resolved PATH into a
+        # committed file bakes in one machine's layout and goes stale the moment the
+        # app changes Ruby - and detection re-runs on every invocation anyway. `env`
+        # is for what pinspec cannot work out: database credentials, feature flags.
+        File.write(path, Config.new(app_path, {
+                                      "cases" => Inputs::Corpus::DEFAULT_MAX_CASES,
+                                      "boots" => 2
+                                    }, path).to_yaml_document)
+
+        row "wrote", path
+        row "rails", profile.rails_version || "unknown"
+        row "ruby", runtime.ruby_version
+        row "runtime", runtime.detected? ? "#{runtime.manager}, detected on each run" : "this shell's Ruby"
+        puts
+
+        if runtime.note
+          puts runtime.note
+          puts
+        end
+
+        puts "Now: pinspec pin app/services/your_service.rb"
+      end
+    end
+
+    desc "plan TARGET", "Diagnostic: the world pinspec would build, without running anything"
     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)
@@ -33,7 +113,7 @@ module Pinspec
           target:    target_profile,
           plan:      setup_plan,
           schema:    app_profile.schema,
-          max_cases: options[:cases]
+          max_cases: setting('cases', Inputs::Corpus::DEFAULT_MAX_CASES)
         )
 
         print_plan(setup_plan)
@@ -45,6 +125,7 @@ module Pinspec
     desc "analyze [APP_PATH]", "App profile: schema, factories, auth, tenancy, hazards"
     def analyze(app_path = ".")
       guarded do
+        Config.load(app_path)
         profile = Analyzer::AppProfileReader.read(app_path)
 
         print_app(profile)
@@ -56,32 +137,35 @@ module Pinspec
       end
     end
 
-    desc "capture FILE#METHOD", "Run the probe, write observations.json"
+    desc "capture TARGET", "Diagnostic: run the probe only, and write observations.json"
     method_option :app, type: :string, default: ".", desc: "target app root"
     method_option :cases, type: :numeric, default: Inputs::Corpus::DEFAULT_MAX_CASES
     method_option :boots, type: :numeric, default: 2,
                           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 :"app-env", type: :array, default: [], banner: "KEY=VALUE",
+    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)"
-    def capture(target)
+    def capture(*args)
       guarded do
-        file, method = Analyzer::TargetParser.split_target(target)
+        target = target_from(args)
+        file, method = resolve_target(target)
 
         result = Runner::Capture.new(
           app_root:    options[:app],
           target:      file,
           method:      method,
-          max_cases:   options[:cases],
-          boots:       options[:boots],
-          compare_sql: options[:"compare-sql"],
+          max_cases:   setting('cases', Inputs::Corpus::DEFAULT_MAX_CASES),
+          boots:       setting('boots', 2),
+          compare_sql: setting('compare-sql', false),
           sandbox_env: app_env,
-          sample:      options[:sample],
+          sample:      setting('sample', false),
           redact:      !options[:"no-redact"]
         ).run
 
@@ -91,7 +175,7 @@ module Pinspec
       end
     end
 
-    desc "pin FILE#METHOD", "Plan + capture + emit + verify"
+    desc "pin TARGET", "Capture, emit and verify. TARGET is FILE, FILE#METHOD or a directory"
     method_option :app, type: :string, default: ".", desc: "target app root"
     method_option :cases, type: :numeric, default: Inputs::Corpus::DEFAULT_MAX_CASES
     method_option :boots, type: :numeric, default: 2
@@ -99,27 +183,59 @@ 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 :"app-env", type: :array, default: [], banner: "KEY=VALUE",
+    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)"
-    def pin(target)
+    method_option :snapshot, type: :string, hide: true
+    def pin(*args)
       guarded do
-        refuse_unbuilt_backend!
+        target = target_from(args)
+        warn_about_retired_flags!
         warn_about_redaction!
-        file, method = Analyzer::TargetParser.split_target(target)
+
+        return pin_directory(target) if File.directory?(target)
+
+        pin_one(target)
+      end
+    end
+
+    no_commands do
+      def pin_directory(path)
+        files = Batch.targets_in(path)
+        raise TargetNotFound, "no .rb files under #{path}" if files.empty?
+
+        # 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
+
+        print_batch(report, path)
+
+        raise NothingStableToPin,
+              "nothing under #{path} could be pinned. Each refusal above says why." unless report.anything_pinned?
+      end
+
+      def pin_one(target, quiet: false)
+        file, method = resolve_target(target)
 
         capture = Runner::Capture.new(
           app_root: options[:app], target: file, method: method,
-          max_cases: options[:cases], boots: options[:boots], sandbox_env: app_env,
-          sample: options[:sample], redact: !options[:"no-redact"]
+          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"] && setting("redact", true)
         ).run
 
-        print_capture(capture)
+        print_capture(capture) unless quiet
         raise NothingStableToPin, nothing_stable_message(capture.stability) if capture.stability.nothing_to_pin?
 
         written = Emit::SpecWriter.new(
@@ -129,19 +245,27 @@ module Pinspec
           force: options[:force]
         ).write!
 
-        puts
-        print_written(written)
+        unless quiet
+          puts
+          print_written(written)
+        end
 
-        return if options[:"skip-verify"]
+        if options[:"skip-verify"]
+          return Batch::Outcome.new(file: file, target: capture.target.qualified_name, status: :pinned,
+                                    detail: "not verified", pinned: written.pinned_cases.size,
+                                    spec_path: written.spec_path)
+        end
 
         outcomes = Verify::Verifier.new(
           app_root: options[:app], spec_path: written.spec_path,
-          level: options[:"verify-level"].to_sym, env: app_env,
+          level: setting("verify-level", "full").to_sym, env: app_env,
           captured_tz: capture.plan.env_fingerprint[:tz]
         ).verify
 
-        puts
-        print_verification(outcomes)
+        unless quiet
+          puts
+          print_verification(outcomes)
+        end
 
         report_path = Report::Summary.new(
           app_root: options[:app], profile: Analyzer::AppProfileReader.read(options[:app]),
@@ -149,27 +273,36 @@ module Pinspec
           stability: capture.stability, written: written, outcomes: outcomes
         ).write!
 
-        puts
-        row "report", report_path
+        unless quiet
+          puts
+          row "report", report_path
+        end
 
         raise VerifyFailed, verify_failed_message(outcomes) unless outcomes.all?(&:green?)
+
+        Batch::Outcome.new(file: file, target: capture.target.qualified_name, status: :pinned,
+                           detail: outcomes.map(&:config).join(", "), pinned: written.pinned_cases.size,
+                           spec_path: written.spec_path)
       end
     end
 
-    desc "validate FILE#METHOD", "Mutation-score a pin, one aspect at a time"
+    desc "validate TARGET", "Mutation-score a pin, one aspect at a time"
     method_option :app, type: :string, default: ".", desc: "target app root"
     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 :"app-env", type: :array, default: [], banner: "KEY=VALUE",
+    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(target)
+    def validate(*args)
       guarded do
-        file, method = Analyzer::TargetParser.split_target(target)
+        target = target_from(args)
+        file, method = resolve_target(target)
 
         capture = Runner::Capture.new(
           app_root: options[:app], target: file, method: method,
-          max_cases: options[:cases], sandbox_env: app_env
+          max_cases: setting('cases', Inputs::Corpus::DEFAULT_MAX_CASES), sandbox_env: app_env
         ).run
 
         raise NothingStableToPin, nothing_stable_message(capture.stability) if capture.stability.nothing_to_pin?
@@ -180,7 +313,7 @@ module Pinspec
           app_root: options[:app], target: capture.target, plan: capture.plan,
           corpus: capture.corpus, stability: capture.stability,
           fk_map: profile.schema.fk_map,
-          env: app_env, test_command: options[:"test-command"]
+          env: app_env, test_command: setting("test-command", nil)
         ).run
 
         print_scores(report)
@@ -214,21 +347,149 @@ module Pinspec
 
     private
 
+    # In 0.1.0 --app-env was a Thor array option, so `--app-env A=1 B=2 C=3` was the
+    # documented way to pass several. Making it repeatable fixed the option
+    # swallowing the target, but it would also have silently reinterpreted every
+    # existing invocation - the extra pairs would land here as positionals. So they
+    # are still understood, and the target is whichever positional is not a
+    # KEY=VALUE pair, wherever it sits on the line.
+    LEGACY_ENV_PAIR = /\A[A-Za-z_][A-Za-z0-9_]*=/
+
+    def target_from(args)
+      targets, pairs = args.partition { |arg| !arg.match?(LEGACY_ENV_PAIR) }
+      @legacy_env = pairs
+
+      if targets.empty?
+        raise TargetNotFound, no_target_message
+      end
+
+      if targets.size > 1
+        raise AmbiguousTarget,
+              "more than one target given (#{targets.join(', ')}). pinspec pins one " \
+              "file, one FILE#METHOD, or one directory per run."
+      end
+
+      warn_about_legacy_env unless pairs.empty?
+      targets.first
+    end
+
+    def warn_about_legacy_env
+      warn "pinspec: `--app-env A=1 B=2` is the 0.1.0 form and still works. " \
+           "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
+
+    # File first, then anything typed on the command line, so a flag always wins.
     def app_env
-      Array(options[:"app-env"]).each_with_object({}) do |pair, out|
+      pairs = Array(@legacy_env) + Array(options[:"app-env"])
+
+      typed = pairs.each_with_object({}) do |pair, out|
         key, value = pair.split("=", 2)
         out[key] = value.to_s
       end
+
+      config.env.merge(typed)
+    end
+
+    def setting(key, default)
+      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!
@@ -264,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
 
@@ -300,17 +561,18 @@ module Pinspec
       stability = result.stability
 
       puts "capture  #{result.target.qualified_name}"
-      row "plan", "#{result.plan.plan_id} (isolation #{result.plan.isolation})"
-      row "runs", "#{stability.runs} boots"
-      row "cases", result.corpus.size
-      row "stable", "#{stability.stable.size} of #{result.corpus.size}"
-      row "compared", stability.compared_fields.join(", ")
-      row "observations", result.output_path
-
-      unless stability.stable.empty?
-        puts
-        puts "  stable, and therefore pinnable:"
-        stability.stable.each { |verdict| puts "    #{verdict.case_id}  #{summarize(verdict.observation)}" }
+      row "stable", "#{stability.stable.size} of #{result.corpus.size} cases, over #{stability.runs} boots"
+
+      if verbose?
+        row "plan", "#{result.plan.plan_id} (isolation #{result.plan.isolation})"
+        row "compared", stability.compared_fields.join(", ")
+        row "observations", result.output_path
+
+        unless stability.stable.empty?
+          puts
+          puts "  stable, and therefore pinnable:"
+          stability.stable.each { |verdict| puts "    #{verdict.case_id}  #{summarize(verdict.observation)}" }
+        end
       end
 
       return if stability.unstable.empty?
@@ -346,10 +608,11 @@ module Pinspec
 
     def print_written(written)
       puts "emitted  #{written.spec_path}"
-      written.support_paths.each { |path| row "support", path }
-      row "pinned", written.pinned_cases.join(", ")
-      row "aspects", written.aspects.reject { |_, count| count.zero? }
-                            .map { |aspect, count| "#{count} #{aspect}" }.join(", ")
+      row "pinned", "#{written.pinned_cases.size} case(s): " +
+                    written.aspects.reject { |_, count| count.zero? }
+                           .map { |aspect, count| "#{count} #{aspect}" }.join(", ")
+
+      written.support_paths.each { |path| row "support", path } if verbose?
     end
 
     def print_verification(outcomes)
@@ -578,8 +841,33 @@ module Pinspec
       values.empty? ? "(none)" : values.join(", ")
     end
 
+    def verbose?
+      options[:verbose]
+    end
+
     def row(label, value)
       puts format("  %-14s %s", label, value)
     end
+
+    def print_batch(report, path)
+      width = report.outcomes.map { |o| File.basename(o.file).length }.max.to_i
+
+      report.outcomes.each do |outcome|
+        name = File.basename(outcome.file).ljust(width)
+
+        puts case outcome.status
+             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
+      end
+
+      puts
+      row "pinned", "#{report.pinned.size} of #{report.outcomes.size}"
+      row "skipped", report.refused.size if report.refused.any?
+      row "failed", report.failed.size if report.failed.any?
+      row "specs", File.join(options[:app], Emit::SpecWriter::SPEC_DIR) if report.anything_pinned?
+    end
   end
 end

data/lib/pinspec/config.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pinspec
+  class Config
+    FILENAME = ".pinspec.yml"
+
+    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
+
+    def self.load(app_root)
+      path = File.join(app_root.to_s, FILENAME)
+      return new(app_root, EMPTY, nil) unless File.file?(path)
+
+      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)
+
+      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'} " \
+              "#{unknown.map(&:inspect).join(', ')}. Known keys: #{KEYS.join(', ')}."
+      end
+
+      new(app_root, parsed, path)
+    rescue Psych::SyntaxError => e
+      raise ConfigInvalid, "#{path} is not valid YAML: #{e.message}"
+    end
+
+    attr_reader :path
+
+    def initialize(app_root, data, path)
+      @app_root = app_root
+      @data = data || {}
+      @path = path
+    end
+
+    def exist?
+      !@path.nil?
+    end
+
+    def env
+      raw = @data["env"] || {}
+      raise ConfigInvalid, "#{@path}: `env` must be a mapping of KEY: VALUE" unless raw.is_a?(Hash)
+
+      raw.transform_keys(&:to_s).transform_values(&:to_s)
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # CLI flag beats file beats default. Thor cannot tell a flag that was typed from
+    # one that defaulted, so the caller passes the default separately and an option
+    # equal to it is treated as untyped.
+    def value(key, given, default)
+      return given unless given == default || given.nil?
+
+      fetched = @data[key.to_s]
+      fetched.nil? ? default : fetched
+    end
+
+    def to_yaml_document
+      <<~YAML
+        # pinspec settings. Every key here is a CLI flag you would otherwise repeat;
+        # a flag on the command line still wins.
+        #
+        # The app's Ruby is detected on each run from .ruby-version or .tool-versions,
+        # so it is deliberately not recorded here. Use `env` only for what pinspec
+        # cannot work out for itself:
+        #
+        #   env:
+        #     DATABASE_USERNAME: myapp
+        #
+        #{YAML.dump(@data).sub(/\A---\n/, "").chomp}
+      YAML
+    end
+  end
+end