pinspec 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f80ae1282baf0c4d24f694ced4a28e3333bd2db013a6b5a50c64dbf24349e51
-  data.tar.gz: 3a970d963883ed690524562afa726ab0690aa6f5325bd3e65400c267b34ffb0f
+  metadata.gz: 3725fabfaf5ca20380e8006be8da9324aa2e1f044dba71ee7cd867360a42fe57
+  data.tar.gz: 4d83085aaa24d6b1eb97577f32fdc8bb4696c28469bacfab8187c04cd12f3e5a
 SHA512:
-  metadata.gz: e8d0773aa7d21161ba1a6b2c2cd64634dc0edeaca7bd9b089e92db7ecb76b9cc77e091316f5a97fa008b25cd790dd8e155777eede702138f14e08ebd9019d93f
-  data.tar.gz: 76952dd81076d9e47aef99bbea8b181c6946312127a1360ea3ccd8ba7f0bbccfb25a511104a741292c920924e04803c35eb7d1f19e9187180954859f51430523
+  metadata.gz: 62faf9d5c24304fe2d122d05ddf17634185728764e4a59dd5bdbba8c953e718d748497abd562d95e77ed35c8dc4b1477a1bc0732fb403498f846498f3572cbd3
+  data.tar.gz: 5af0cf46d7730057402c1b3dcc0679ec495be239b94fba0aecae7e21a1029fdedfa15f053404f7f52e5594e9706522820cac109fe68abf9de24f7da323f9a121

data/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 0.2.0 - 2026-08-15
+
+Ergonomics. 0.1.0 worked, but a run against a real application needed six lines of
+environment before it would start, and almost none of it was intent.
+
+### The app's Ruby is detected, not declared
+
+pinspec reads the target application's `.ruby-version` or `.tool-versions` and
+locates that Ruby under rvm, rbenv, asdf, mise or chruby on every run. Only
+bundler's variables are scrubbed from the child process now; `GEM_HOME` and
+`GEM_PATH` are left alone, which is what previously forced every invocation to hand
+the application's gemset back by hand. When the declared Ruby cannot be found,
+the failure names the version, the one in use, and the exact `--app-env` line to
+pass.
+
+A patch-level difference is treated as the same runtime: 3.4.2 and 3.4.6 run the
+same code, and relocating for it would fail on a machine that has only one.
+
+### `.pinspec.yml`
+
+`pinspec init` writes it. It holds the flags you would otherwise repeat - `cases`,
+`boots`, `sample`, `verify-level`, `test-command`, and an `env` mapping for what
+pinspec cannot work out, such as database credentials. A flag on the command line
+always wins. An unknown key is an error naming the key and listing the valid ones,
+rather than silence that reads as "the setting does not work".
+
+The detected runtime is deliberately **not** written to that file: recording one
+machine's `PATH` bakes in a layout that goes stale the moment the app changes Ruby,
+and detection re-runs anyway.
+
+### Targets
+
+- A bare file assumes `#call`: `pinspec pin app/services/invoice_calculator.rb`.
+- `--app-env` is repeatable (`--app-env A=1 --app-env B=2`) instead of an array
+  option, so the target can appear anywhere on the line. As an array option it
+  silently swallowed the positional target unless that came first.
+
+  **The 0.1.0 form keeps working.** `--app-env A=1 B=2 C=3` was what 0.1.0
+  documented, and changing the option type would have silently reinterpreted every
+  existing invocation rather than failing on it. Trailing `KEY=VALUE` pairs are
+  still collected, the target is whichever argument is not a pair, and using the old
+  form prints a note suggesting the new one. Nothing anyone scripted against 0.1.0
+  needs to change.
+- **A directory pins everything under it.** Refusals are reported and the run
+  continues, since one target that takes a block should not end a run over forty.
+  The summary separates what was pinned, what was skipped and why, and what failed
+  verification. Exits non-zero when nothing pinned.
+
+### Output
+
+Default output is the target, the stable count, what was pinned, the three verify
+results and the report path. The plan id, compared fields and per-case detail move
+behind `--verbose`. `pin` leads the command list, and `plan` and `capture` are
+labelled diagnostics.
+
+### Compatibility
+
+Nothing from 0.1.0 breaks. Both `--app-env` forms are accepted, `FILE#METHOD` still
+works alongside the new bare-file shorthand, every flag keeps its name and meaning,
+and `.pinspec.yml` is optional - an application without one behaves exactly as it
+did, except that its Ruby is now found automatically.
+
+### Fixed
+
+- **Two pinspec runs against the same application corrupted each other.** The probe
+  was written to a fixed `tmp/pinspec/probe.rb`, so a second run overwrote it between
+  the first run's two boots. The failure was silent rather than loud: the stability
+  filter compared one target's observations against another's and reported the target
+  as unstable, or crashed looking up a case id belonging to a different corpus. Each
+  run now writes its own probe, named after the process, and removes it on success -
+  keeping it after a failure, where it is the evidence. Found by running two captures
+  against one application at once.
+- Batch discovery matched its skip patterns against the absolute path, so an
+  application living anywhere under a directory named `spec` had every file skipped.
+  Patterns now match the path relative to the directory being pinned.
+- `analyze` did not read `.pinspec.yml`, so a typo in it stayed silent for the
+  command people run first.
+
 ## 0.1.0 - 2026-08-13
 
 First release.

data/README.md

@@ -8,24 +8,28 @@ code does today, and then verifies that file passes in your app's own test
 environment.
 
 ```bash
-pinspec pin app/services/invoice_calculator.rb#call --app .
+cd myapp
+pinspec pin app/services/invoice_calculator.rb
 ```
 
 ```
 capture  InvoiceCalculator#call
-  runs           2 boots
-  stable         2 of 2
+  stable         3 of 3 cases, over 2 boots
 
 emitted  spec/characterization/invoice_calculator_call_spec.rb
-  pinned         c001, c002
-  aspects        2 return, 2 jobs
+  pinned         3 case(s): 3 return, 3 jobs
 
 verify
-  isolated       green (4 examples)
-  hostile        green (4 examples)
-  neighbored     green (4 examples)
+  isolated       green (6 examples)
+  hostile        green (6 examples)
+  neighbored     green (6 examples)
+
+  report         tmp/pinspec/report.md
 ```
 
+`--verbose` adds the plan id, the fields compared for stability, and a line per
+pinned case.
+
 A pin freezes current behaviour. It is not a claim that the behaviour is correct —
 bugs get pinned on purpose, so a refactor cannot change them silently.
 
@@ -39,21 +43,57 @@ Ruby >= 3.2. Rails >= 6.0 in the target app. PostgreSQL, MySQL and SQLite all wo
 pinspec adds no database gem, because everything that touches your data runs inside
 your app through `rails runner`.
 
+Your app almost certainly runs on a different Ruby than pinspec does. That is fine
+and needs no configuration: pinspec reads your app's `.ruby-version` or
+`.tool-versions` and finds that Ruby under rvm, rbenv, asdf, mise or chruby on each
+run. If it cannot, it tells you the exact `--app-env` line to pass.
+
+For anything pinspec cannot work out for itself — database credentials, a feature
+flag — record it once:
+
+```bash
+pinspec init
+```
+
+That writes `.pinspec.yml`, which holds the flags you would otherwise repeat. A flag
+on the command line always wins.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `pinspec analyze [APP]` | App profile, schema, factories and hazards. Reads files only — no boot, no database. |
-| `pinspec plan FILE#METHOD --app PATH` | The world it would build, and the arguments it would pass. Still no execution. |
-| `pinspec capture FILE#METHOD --app PATH` | Runs the probe in your app, writes `observations.json`. |
-| `pinspec pin FILE#METHOD --app PATH` | Capture, emit the spec, verify it. |
-| `pinspec validate FILE#METHOD --app PATH` | Mutation-scores the pin, one aspect at a time. Needs Ruby >= 3.4 and `mutineer`. |
-| `pinspec report --app PATH` | Prints the last run's markdown report. |
+| `pinspec pin TARGET` | Capture, emit the spec, verify it. This is the one you want. |
+| `pinspec init` | Write `.pinspec.yml` so later runs need no flags. |
+| `pinspec analyze` | App profile, schema, factories and hazards. Reads files only — no boot, no database. |
+| `pinspec validate TARGET` | Mutation-scores the pin, one aspect at a time. Needs Ruby >= 3.4 and `mutineer`. |
+| `pinspec report` | Prints the last run's markdown report. |
+| `pinspec plan TARGET` | Diagnostic: the world it would build, without running anything. |
+| `pinspec capture TARGET` | Diagnostic: run the probe only, and write `observations.json`. |
 
-Useful flags: `--cases N`, `--boots N`, `--sample` (read real rows from your
-development database), `--no-redact`, `--force`, `--app-env KEY=VALUE`.
+`TARGET` is a file, a `FILE#METHOD`, or a directory:
 
-The target comes first. `--app-env` is an array option and will swallow it otherwise.
+```bash
+pinspec pin app/services/invoice_calculator.rb          # assumes #call
+pinspec pin app/services/invoice_calculator.rb#total    # a different method
+pinspec pin app/services                                # everything under it
+```
+
+Pinning a directory keeps going when a target is refused, and prints one summary:
+
+```
+  pinned   invoice_calculator.rb  2 case(s), verified
+  skipped  report_builder.rb      BlockRequired
+  pinned   status_reporter.rb     2 case(s), verified
+
+  pinned         2 of 3
+  skipped        1
+```
+
+Useful flags: `--cases N`, `--boots N`, `--sample` (read real rows from your
+development database), `--no-redact`, `--force`, `--verbose`, and `--app-env KEY=VALUE`
+for the rare case where the runtime cannot be detected. `--app-env` is repeatable;
+the older `--app-env A=1 B=2` form is still accepted. Anything you find yourself
+repeating belongs in `.pinspec.yml`.
 
 ## Verification
 
@@ -112,6 +152,7 @@ sources are hashed, so a committed spec does not map back to production rows.
 | `db/structure.sql` instead of `db/schema.rb` | `SchemaFormatUnsupported` | 6 |
 | Rails below 6.0 | `UnsupportedRailsVersion` | 10 |
 | no case was stable across boots | `NothingStableToPin` | 8 |
+| `.pinspec.yml` has an unknown key or is not valid YAML | `ConfigInvalid` | 13 |
 
 It will not pass `nil` for a model it could not build: the target would raise on nil,
 and that error would be pinned as though your application produced it.

data/lib/pinspec/analyzer/target_parser.rb

@@ -60,14 +60,19 @@ module Pinspec
           new(file_path, method_name).parse
         end
 
+        DEFAULT_METHOD = "call"
+
         def split_target(target)
-          unless target.to_s.include?("#")
+          text = target.to_s
+          return text.split("#", 2) if text.include?("#")
+
+          unless text.end_with?(".rb")
             raise ArgumentError,
-                  "target must be FILE#METHOD (got #{target.inspect}); " \
-                  "e.g. app/services/invoice_calculator.rb#call"
+                  "target must be a Ruby file, optionally with #METHOD " \
+                  "(got #{target.inspect}); e.g. app/services/invoice_calculator.rb#call"
           end
 
-          target.split("#", 2)
+          [text, DEFAULT_METHOD]
         end
       end
 

data/lib/pinspec/batch.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pinspec
+  class Batch
+    SKIP_PATTERNS = [%r{/concerns/}, %r{_spec\.rb\z}, %r{/spec/}, %r{/test/}].freeze
+
+    Outcome = Data.define(:file, :target, :status, :detail, :pinned, :spec_path) do
+      def pinned?
+        status == :pinned
+      end
+
+      def refused?
+        status == :refused
+      end
+    end
+
+    Report = Data.define(:outcomes) do
+      def pinned
+        outcomes.select(&:pinned?)
+      end
+
+      def refused
+        outcomes.select(&:refused?)
+      end
+
+      def failed
+        outcomes.reject { |outcome| outcome.pinned? || outcome.refused? }
+      end
+
+      def anything_pinned?
+        !pinned.empty?
+      end
+    end
+
+    # Patterns match the path RELATIVE to the directory being pinned. Matching the
+    # absolute path means an app that happens to live under a directory called
+    # `spec` has every one of its files skipped.
+    def self.targets_in(path)
+      return [path] if File.file?(path)
+
+      root = File.expand_path(path)
+
+      Dir.glob(File.join(root, "**", "*.rb")).reject do |file|
+        relative = file.delete_prefix("#{root}/")
+
+        SKIP_PATTERNS.any? { |pattern| "/#{relative}".match?(pattern) }
+      end.sort
+    end
+
+    def initialize(files, &pin)
+      @files = files
+      @pin = pin
+    end
+
+    # A refusal is information, not a stop: one target that takes a block must not
+    # end a run over a directory of forty.
+    def run
+      Report.new(outcomes: @files.map { |file| attempt(file) })
+    end
+
+    private
+
+    def attempt(file)
+      @pin.call(file)
+    rescue UnresolvableSetup, BlockRequired, AmbiguousTarget, TargetNotFound,
+           NothingStableToPin, UnsupportedRailsVersion => e
+      Outcome.new(file: file, target: nil, status: :refused, detail: reason_for(e),
+                  pinned: 0, spec_path: nil)
+    rescue VerifyFailed, ProbeFailure => e
+      Outcome.new(file: file, target: nil, status: :failed, detail: e.message.lines.first.to_s.strip,
+                  pinned: 0, spec_path: nil)
+    end
+
+    def reason_for(error)
+      return "#{error.class.name.split('::').last}(#{error.reason})" if error.respond_to?(:reason)
+
+      error.class.name.split("::").last
+    end
+  end
+end

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 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,7 +30,44 @@ 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 "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"
@@ -33,7 +85,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 +97,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 +109,33 @@ 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 :"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
+        target = target_from(args)
         file, method = Analyzer::TargetParser.split_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 +145,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
@@ -101,25 +155,51 @@ module Pinspec
                          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 :"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)
+    def pin(*args)
       guarded do
+        target = target_from(args)
         refuse_unbuilt_backend!
         warn_about_redaction!
+
+        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?
+
+        puts "pinning #{files.size} file(s) under #{path}"
+        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 = Analyzer::TargetParser.split_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"]
         ).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 +209,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 +237,34 @@ 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 :"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
+        target = target_from(args)
         file, method = Analyzer::TargetParser.split_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 +275,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,11 +309,57 @@ 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 given. Pass a file, a FILE#METHOD, or a directory: " \
+              "pinspec pin app/services/invoice_calculator.rb"
+      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
+
+    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!
@@ -300,17 +441,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 +488,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 +721,32 @@ 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  %d case(s), verified", name, 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,81 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pinspec
+  class Config
+    FILENAME = ".pinspec.yml"
+
+    KEYS = %w[cases boots sample redact compare-sql verify-level snapshot test-command env].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)
+
+      unknown = parsed.keys.map(&:to_s) - 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

data/lib/pinspec/errors.rb

@@ -79,6 +79,10 @@ module Pinspec
     self.exit_code = 11
   end
 
+  class ConfigInvalid < Error
+    self.exit_code = 13
+  end
+
   class PinspecInternalError < Error
     self.exit_code = 12
   end

data/lib/pinspec/inputs/sample_runner.rb

@@ -70,9 +70,9 @@ module Pinspec
       end
 
       def environment
-        Runner::Sandbox::SCRUBBED_ENV
-          .merge("RAILS_ENV" => @rails_env, "DISABLE_SPRING" => "1", "TZ" => "UTC")
-          .merge(@env)
+        Runner::Runtime.for(@app_root).env
+                       .merge("RAILS_ENV" => @rails_env, "DISABLE_SPRING" => "1", "TZ" => "UTC")
+                       .merge(@env)
       end
 
       def parse(stdout, stderr)

data/lib/pinspec/runner/runtime.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Pinspec
+  module Runner
+    class Runtime
+      MANAGERS = %i[rvm rbenv asdf mise chruby].freeze
+
+      Result = Data.define(:env, :ruby_version, :manager, :note) do
+        def detected?
+          !manager.nil?
+        end
+
+        def same_ruby?
+          manager.nil? && note.nil?
+        end
+      end
+
+      BUNDLER_VARS = %w[
+        BUNDLE_GEMFILE BUNDLE_PATH BUNDLE_BIN_PATH BUNDLE_APP_CONFIG
+        BUNDLER_VERSION BUNDLER_SETUP RUBYOPT RUBYLIB
+      ].freeze
+
+      def self.for(app_root, home: Dir.home, current: RUBY_VERSION)
+        new(app_root, home: home, current: current).resolve
+      end
+
+      def initialize(app_root, home: Dir.home, current: RUBY_VERSION)
+        @app_root = app_root
+        @home = home
+        @current = current
+      end
+
+      def resolve
+        wanted = declared_version
+        return Result.new(env: scrub, ruby_version: @current, manager: nil, note: nil) if wanted.nil?
+        return Result.new(env: scrub, ruby_version: @current, manager: nil, note: nil) if satisfied_by_current?(wanted)
+
+        found = MANAGERS.filter_map { |manager| send(:"#{manager}_env", wanted)&.then { |e| [manager, e] } }.first
+
+        if found.nil?
+          return Result.new(
+            env: scrub, ruby_version: wanted, manager: nil,
+            note: "#{@app_root} declares Ruby #{wanted} and this is #{@current}, but no " \
+                  "installation of #{wanted} was found under rvm, rbenv, asdf, mise or " \
+                  "chruby. Pass the app's runtime explicitly:\n" \
+                  "  --app-env PATH=/path/to/ruby-#{wanted}/bin:$PATH"
+          )
+        end
+
+        manager, env = found
+        Result.new(env: scrub.merge(env), ruby_version: wanted, manager: manager, note: nil)
+      end
+
+      def declared_version
+        from_file(".ruby-version") || from_tool_versions
+      end
+
+      private
+
+      # Only bundler's variables are removed. GEM_HOME and GEM_PATH are left alone:
+      # dropping them is what forced every invocation to hand the app's gemset back
+      # by hand, and they are only wrong when the app runs on a different Ruby - in
+      # which case the detected runtime overwrites them anyway.
+      def scrub
+        BUNDLER_VARS.to_h { |name| [name, nil] }
+      end
+
+      def from_file(name)
+        path = File.join(@app_root, name)
+        return nil unless File.file?(path)
+
+        Analyzer::Source.read(path).strip[/\d+\.\d+(\.\d+)?/]
+      end
+
+      def from_tool_versions
+        path = File.join(@app_root, ".tool-versions")
+        return nil unless File.file?(path)
+
+        Analyzer::Source.read(path)[/^\s*ruby\s+(\S+)/, 1]&.[](/\d+\.\d+(\.\d+)?/)
+      end
+
+      # A patch-level difference is not worth relocating the runtime for: 3.3.0 and
+      # 3.3.6 run the same code. A minor difference is.
+      def satisfied_by_current?(wanted)
+        @current == wanted || series(@current) == series(wanted)
+      end
+
+      def series(version)
+        version.to_s.split(".").first(2).join(".")
+      end
+
+      def rvm_env(wanted)
+        root = File.join(@home, ".rvm")
+        ruby = File.join(root, "rubies", "ruby-#{wanted}", "bin")
+        return nil unless File.directory?(ruby)
+
+        gems = File.join(root, "gems", "ruby-#{wanted}")
+        env = { "PATH" => prepend(ruby) }
+        if File.directory?(gems)
+          env["GEM_HOME"] = gems
+          env["GEM_PATH"] = "#{gems}:#{gems}@global"
+        end
+        env
+      end
+
+      def rbenv_env(wanted)
+        bin = File.join(@home, ".rbenv", "versions", wanted, "bin")
+        File.directory?(bin) ? { "PATH" => prepend(bin), "RBENV_VERSION" => wanted } : nil
+      end
+
+      def asdf_env(wanted)
+        bin = File.join(@home, ".asdf", "installs", "ruby", wanted, "bin")
+        File.directory?(bin) ? { "PATH" => prepend(bin) } : nil
+      end
+
+      def mise_env(wanted)
+        bin = File.join(@home, ".local", "share", "mise", "installs", "ruby", wanted, "bin")
+        File.directory?(bin) ? { "PATH" => prepend(bin) } : nil
+      end
+
+      def chruby_env(wanted)
+        bin = File.join(@home, ".rubies", "ruby-#{wanted}", "bin")
+        File.directory?(bin) ? { "PATH" => prepend(bin) } : nil
+      end
+
+      def prepend(bin)
+        [bin, ENV.fetch("PATH", "")].reject(&:empty?).join(File::PATH_SEPARATOR)
+      end
+    end
+  end
+end

data/lib/pinspec/runner/sandbox.rb

@@ -8,7 +8,17 @@ module Pinspec
   module Runner
     class Sandbox
       PROBE_DIR = "tmp/pinspec"
-      PROBE_FILE = "probe.rb"
+
+      # One probe file per run. A fixed path means two pinspec runs against the same
+      # application overwrite each other's probe between boots, and the result is not
+      # an error: the stability filter compares one target's observations against
+      # another's and reports the target as unstable, or crashes looking up a case id
+      # that belongs to a different corpus. Silent and wrong, which is worse than a
+      # lock. `pinspec pin app/services` is sequential, but a developer with two
+      # terminals or a CI that fans out is not.
+      def self.probe_filename(pid: Process.pid, object_id: nil)
+        "probe-#{pid}-#{object_id || rand(1 << 24)}.rb"
+      end
 
       DEFAULT_TIMEOUT = 600
 
@@ -18,18 +28,7 @@ module Pinspec
         "RAILS_ENV" => "test"
       }.freeze
 
-      SCRUBBED_ENV = {
-        "BUNDLE_GEMFILE" => nil,
-        "BUNDLE_PATH" => nil,
-        "BUNDLE_BIN_PATH" => nil,
-        "BUNDLE_APP_CONFIG" => nil,
-        "BUNDLER_VERSION" => nil,
-        "BUNDLER_SETUP" => nil,
-        "RUBYOPT" => nil,
-        "RUBYLIB" => nil,
-        "GEM_HOME" => nil,
-        "GEM_PATH" => nil
-      }.freeze
+      SCRUBBED_ENV = Runtime::BUNDLER_VARS.to_h { |name| [name, nil] }.freeze
 
       Result = Data.define(:run, :observations, :env, :plan_id, :stderr) do
         def observation(case_id)
@@ -46,7 +45,7 @@ module Pinspec
       end
 
       def probe_path
-        File.join(@app_root, PROBE_DIR, PROBE_FILE)
+        @probe_path ||= File.join(@app_root, PROBE_DIR, self.class.probe_filename(object_id: object_id))
       end
 
       def write_probe!
@@ -58,16 +57,24 @@ module Pinspec
       def capture(boots: 2)
         write_probe!
 
-        (1..boots).map do |run|
-          execute(run: run, seed: 40 + run)
-        end
+        results = (1..boots).map { |run| execute(run: run, seed: 40 + run) }
+
+        # Removed only on success. A probe left behind after a failure is the
+        # evidence; one left behind after every run just fills tmp/ with files a
+        # reader cannot tell apart.
+        FileUtils.rm_f(probe_path)
+        results
+      end
+
+      def runtime
+        @runtime ||= Runtime.for(@app_root)
       end
 
       private
 
       def execute(run:, seed:)
         command = runner_command
-        env = SCRUBBED_ENV
+        env = runtime.env
               .merge(FORCED_ENV)
               .merge("PINSPEC_SHUFFLE_SEED" => seed.to_s)
               .merge(@env)
@@ -77,6 +84,7 @@ module Pinspec
         unless status.success?
           raise ProbeFailure,
                 "the probe exited #{status.exitstatus} in #{@app_root}.\n" \
+                "#{runtime.note ? "#{runtime.note}\n\n" : ''}" \
                 "#{stderr.to_s.lines.last(15).join}"
         end
 
@@ -108,7 +116,7 @@ module Pinspec
       def runner_command
         return @runner if @runner
 
-        relative = File.join(PROBE_DIR, PROBE_FILE)
+        relative = File.join(PROBE_DIR, File.basename(probe_path))
 
         if File.file?(File.join(@app_root, "Gemfile"))
           ["bundle", "exec", "rails", "runner", relative]

data/lib/pinspec/verify/verifier.rb

@@ -90,9 +90,9 @@ module Pinspec
       end
 
       def environment
-        Runner::Sandbox::SCRUBBED_ENV
-          .merge("RAILS_ENV" => "test", "DISABLE_SPRING" => "1", "TZ" => @captured_tz)
-          .merge(@env)
+        Runner::Runtime.for(@app_root).env
+                       .merge("RAILS_ENV" => "test", "DISABLE_SPRING" => "1", "TZ" => @captured_tz)
+                       .merge(@env)
       end
 
       def parse(stdout)

data/lib/pinspec/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Pinspec
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 
   PROBE_VERSION      = 3
   SERIALIZER_VERSION = 3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rehan Munir
@@ -80,7 +80,9 @@ files:
 - lib/pinspec/analyzer/schema_reader.rb
 - lib/pinspec/analyzer/source.rb
 - lib/pinspec/analyzer/target_parser.rb
+- lib/pinspec/batch.rb
 - lib/pinspec/cli.rb
+- lib/pinspec/config.rb
 - lib/pinspec/emit/namer.rb
 - lib/pinspec/emit/spec_writer.rb
 - lib/pinspec/emit/stability_filter.rb
@@ -94,6 +96,7 @@ files:
 - lib/pinspec/report/summary.rb
 - lib/pinspec/runner/capture.rb
 - lib/pinspec/runner/probe_generator.rb
+- lib/pinspec/runner/runtime.rb
 - lib/pinspec/runner/sandbox.rb
 - lib/pinspec/setup/context_builder.rb
 - lib/pinspec/setup/dependency_resolver.rb