pinspec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f80ae1282baf0c4d24f694ced4a28e3333bd2db013a6b5a50c64dbf24349e51
+  data.tar.gz: 3a970d963883ed690524562afa726ab0690aa6f5325bd3e65400c267b34ffb0f
+SHA512:
+  metadata.gz: e8d0773aa7d21161ba1a6b2c2cd64634dc0edeaca7bd9b089e92db7ecb76b9cc77e091316f5a97fa008b25cd790dd8e155777eede702138f14e08ebd9019d93f
+  data.tar.gz: 76952dd81076d9e47aef99bbea8b181c6946312127a1360ea3ccd8ba7f0bbccfb25a511104a741292c920924e04803c35eb7d1f19e9187180954859f51430523

data/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+## 0.1.0 - 2026-08-13
+
+First release.
+
+`pinspec pin FILE#METHOD --app PATH` resolves a Rails service object or model
+method, builds the world it needs, runs it inside the application, writes an RSpec
+file that freezes what it observed, and verifies that file in the application's own
+test environment.
+
+### Commands
+
+- `analyze` - application profile, schema, factories and hazards. Static: no boot,
+  no database connection.
+- `plan` - the world pinspec would build and the arguments it would pass. Pure data,
+  readable before anything runs.
+- `capture` - runs the generated probe in the application and writes
+  `observations.json`.
+- `pin` - capture, emit the spec, verify it.
+- `validate` - mutation-scores a pin one aspect at a time. Requires Ruby >= 3.4 and
+  `mutineer`; refuses with an explanation otherwise.
+- `report` - the markdown report from the last run.
+
+### Analysis
+
+- Targets resolve from a static parse across six construction shapes: `new`, class
+  method, interactor, `dry_initializer`, `Struct` and model instance, including one
+  level of superclass inheritance. Constructor arguments are part of the invocation
+  surface, so a zero-argument `#call` whose dependencies arrive via `initialize` is
+  supported.
+- `db/schema.rb` is parsed into tables, columns, indexes and a foreign-key map with
+  provenance: a database constraint, a declared association, or an inferred `*_id`
+  column. Constraints win over inferences, and inferences are reported separately.
+  Polymorphic ids are excluded.
+- Association targets resolve against the schema's real table names rather than by
+  pluralising, and tables behind an engine prefix are found through the class a
+  factory declares - so `Spree::Order` resolves to `spree_orders`.
+- factory_bot and factory_girl definitions are indexed from source and never
+  executed, including traits, inheritance through nesting and `parent:`, callbacks,
+  and factories that never persist.
+- Gem, auth, tenancy, soft-delete, versioning, feature-flag, attachment and
+  test-harness detection from `Gemfile.lock` and the helper files, with per-model
+  hazards (`default_scope`, `after_commit`, attachments, `acts_as_tenant`) reported
+  by file and line.
+- Unknown schema statements and column types are recorded rather than fatal.
+
+### Planning and inputs
+
+- A `SetupPlan` is pure data: no connection, no application code, no application
+  process. Its id is content-addressed, so the same target always yields the same
+  plan and a changed plan is visibly different.
+- The environment is pinned before any record exists: frozen clock, seeded
+  randomness, locale, time zone.
+- A factory is used where one exists and is then left to own its own associations;
+  otherwise the required `belongs_to` closure is built from the schema. Nullable
+  associations are left null.
+- A current-user record is built only for a target that could observe one.
+- Boundary values and one-factor-at-a-time variation across constructor and method
+  parameters, interleaved so a small case budget reaches both. One case omits an
+  optional argument entirely, exercising the method's own default expression.
+- `--sample` reads real rows through a generated read-only script in the
+  application's runtime, then rebuilds them as `create!` calls. Personal data is
+  rewritten preserving domain and length; row sources are hashed.
+
+### Capture
+
+- The probe is generated, stdlib-only, and held to a Ruby 2.6 syntax floor, so it
+  runs in the application's Ruby. It can be read before it is run.
+- It refuses to run outside `RAILS_ENV=test`, and honours the suite's isolation
+  regime - rolling back per case, or truncating where the suite does not transact.
+- No database id reaches a snapshot. Foreign keys pointing at plan-built records
+  become refs; other id-shaped values become a wildcard. Ids inside job arguments
+  and GlobalID strings are resolved too.
+- Side-effect sinks are forced to `:test` and cleared after setup, so a factory
+  callback's enqueue is never attributed to the target.
+- Two boots by default, because one process shares warm caches and an input-keyed
+  memo would agree with itself. Cases that differ between boots are reported with a
+  named cause rather than pinned.
+
+### Emitted specs
+
+- The spec forces the capture's answer on every axis rather than inheriting the
+  suite's: isolation regime, queue adapter, clock, seed, locale and zone.
+- Verification runs in three environments - the file alone, a hostile timezone and
+  locale with a different seed, and the file twice in one process.
+- Job and mail assertions are block-scoped. A timezone guard is emitted only for a
+  target that reads the process clock.
+- pinspec overwrites only its own output; anything else needs `--force`.
+- Example names are deterministic. No captured value is sent anywhere: there is no
+  path from the CLI to a language model.
+
+### Refusals
+
+Each carries its own exit code: a target that takes a block, a constructor that
+resolves its own dependencies, a parameter naming a model the application has no
+table, model or factory for, mutually required NOT NULL foreign keys, a NOT NULL
+column whose type has no honest value, attachments, `ros-apartment` tenancy, an
+ambiguous target name, a delegation or `method_missing` redirect,
+`db/structure.sql`, Rails below 6.0, and nothing stable to pin.
+
+pinspec does not pass `nil` for a model it could not build: the target would raise
+on nil and that error would be pinned as though the application produced it.
+
+### Known limitations
+
+- Mutation scores on real service objects are frequently weak. The default corpus
+  builds the smallest world that can exist, and the smallest world often does not
+  reach a target's branches. Read the scores before trusting a pin; `--sample`
+  helps.
+- `after_commit` never fires under transactional isolation, in the capture or in the
+  emitted spec. pinspec does not fake it, and the report says so.
+- Per-case rollback covers the primary writing connection only.
+- Attachments are refused rather than run against an empty blob.
+- Clock and attribute-read detection scans the target's own file, so a transitive
+  callee is invisible. No warning is not proof of no read.
+- `insta` and `approvals` snapshot backends are not implemented; `--snapshot`
+  refuses them rather than silently emitting inline literals.
+
+### Requirements
+
+Ruby >= 3.2 for the CLI, and >= 3.4 for `validate`. Rails >= 6.0 in the target
+application. No database gem is added: everything that touches application data
+runs inside the application through `rails runner`.
+
+### Verified
+
+658 examples on Ruby 3.4.6, 3.3.0 and 3.2.2, each under a normal shell and under
+`LANG=C LC_ALL=C TZ=Etc/GMT+8`. Both isolation regimes are covered end to end by
+Rails applications that boot on PostgreSQL, and the six axes on which the probe
+process and the spec process could disagree are held to agreement by a test that
+fails the build. Also exercised against a large open-source Rails application on
+Spree: six service objects pinned, each green in all three verify configurations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rehan Munir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# pinspec
+
+Characterization tests for legacy Rails codebases.
+
+Point pinspec at a Rails service object or model method. It works out how to invoke
+it, runs it against your test database, writes an RSpec file that freezes what the
+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 .
+```
+
+```
+capture  InvoiceCalculator#call
+  runs           2 boots
+  stable         2 of 2
+
+emitted  spec/characterization/invoice_calculator_call_spec.rb
+  pinned         c001, c002
+  aspects        2 return, 2 jobs
+
+verify
+  isolated       green (4 examples)
+  hostile        green (4 examples)
+  neighbored     green (4 examples)
+```
+
+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.
+
+## Install
+
+```bash
+gem install pinspec
+```
+
+Ruby >= 3.2. Rails >= 6.0 in the target app. PostgreSQL, MySQL and SQLite all work:
+pinspec adds no database gem, because everything that touches your data runs inside
+your app through `rails runner`.
+
+## 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. |
+
+Useful flags: `--cases N`, `--boots N`, `--sample` (read real rows from your
+development database), `--no-redact`, `--force`, `--app-env KEY=VALUE`.
+
+The target comes first. `--app-env` is an array option and will swallow it otherwise.
+
+## Verification
+
+Every pin is checked in three environments, because one run on the machine that
+captured it proves repeatability rather than portability:
+
+- **isolated** — the file alone, as captured.
+- **hostile** — a different timezone, locale and RSpec seed.
+- **neighbored** — the file twice in one process, so accumulated state shows up.
+
+The emitted spec forces the capture's answer on every axis rather than inheriting
+the suite's: isolation regime, queue adapter, clock, seed, locale and zone. A suite
+that truncates instead of transacting, or that runs jobs inline, would otherwise
+turn a green capture into a red or vacuous spec.
+
+## No database ids in a pin
+
+Postgres sequences are not transactional, so a rolled-back case still advances them
+and an id differs on the next run. A foreign key pointing at a record the plan built
+becomes a ref; anything else id-shaped becomes a wildcard:
+
+```ruby
+{"t" => "record", "class" => "Invoice", "attributes" => {
+  "customer_id" => {"t" => "ref", "v" => "customer_1"},
+  "total"       => {"t" => "decimal", "v" => "110.0"}
+}}
+```
+
+Ids also hide in job arguments (`perform_later(record.id)`) and inside GlobalID
+strings (`gid://app/Invoice/22`). Both are resolved to the record they name, or keep
+the model and drop the id.
+
+## Real rows, with the personal data rewritten
+
+`--sample` reads rows from your development database through a generated read-only
+script, then rebuilds them as `create!` calls in the spec. Rewrites preserve **domain
+and length** — `rehan.munir@acme.co` keeps `@acme.co` and its character count — so a
+target that routes on a domain or validates a length behaves as it always did. Row
+sources are hashed, so a committed spec does not map back to production rows.
+
+`--no-redact` turns this off. It writes real personal data into a file you commit.
+
+## It refuses rather than guessing
+
+| Situation | Result | Exit |
+| --- | --- | --- |
+| target takes a block or yields | `BlockRequired` | 4 |
+| constructor resolves its own dependencies, or `super`s into another file | `UnresolvableSetup(:opaque_constructor)` | 5 |
+| a parameter names a model the app has no table, model or factory for | `UnresolvableSetup(:unresolvable_parameter)` | 5 |
+| two tables require each other through NOT NULL foreign keys | `UnresolvableSetup(:association_cycle)` | 5 |
+| a NOT NULL column whose type has no honest value | `UnresolvableSetup(:unknown_column_type)` | 5 |
+| target reads an attachment | `UnresolvableSetup(:attachment)` | 5 |
+| `ros-apartment` tenancy | `UnresolvableSetup(:apartment)` | 5 |
+| name resolves to two definitions | `AmbiguousTarget` | 3 |
+| `delegate` or `method_missing` redirect | `TargetNotFound` | 2 |
+| `db/structure.sql` instead of `db/schema.rb` | `SchemaFormatUnsupported` | 6 |
+| Rails below 6.0 | `UnsupportedRailsVersion` | 10 |
+| no case was stable across boots | `NothingStableToPin` | 8 |
+
+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.
+
+## Mutation scoring
+
+`pinspec validate` grades each aspect of a pin separately, because they are blind to
+different things — a return-value pin does not notice a deleted `perform_later`, and
+a job pin does not notice the arithmetic:
+
+```
+return         66.7% weak (4 killed, 2 survived)
+    survived: statement_removal at line 18 - SyncJob.perform_later(invoice.id)
+jobs           50.0% weak (3 killed, 3 survived)
+    survived: arithmetic at line 14 - +
+
+nothing survived every aspect: together, the pins cover this target.
+```
+
+A pin containing a wildcard or a truncated value is never reported as strong, however
+well it scores. An aspect the pin does not assert is skipped rather than scored, since
+scoring an absent aspect yields a vacuous 100%.
+
+## Known limits
+
+- **Attachments** are refused rather than run against an empty blob.
+- **`after_commit`** never fires under transactional isolation, in the capture or in
+  the emitted spec. pinspec does not fake it, so this is a real divergence from
+  production and the report says so.
+- **Multiple writing databases**: per-case rollback covers the primary writing
+  connection only.
+- **Read and clock detection scans the target's own file.** A transitive callee that
+  reads the current user or the process clock is invisible, so no warning is not proof
+  of no read.
+- **Small worlds make weak pins.** The default corpus builds the smallest world that
+  can exist, which often does not reach a target's branches — mutation scores on real
+  service objects are frequently weak. `--sample` helps; read the scores before
+  trusting a pin.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+LANG=C LC_ALL=C TZ=Etc/GMT+8 bundle exec rspec
+```
+
+That second run matters: pinspec's own hostile verify config sets `LANG=C`, so a
+non-ASCII string literal in shipped source would break it.
+
+Fixtures come in two kinds. Those under `spec/fixtures/targets/` and most of
+`spec/fixtures/apps/` are parsed, never loaded, so they reference constants that do
+not exist in this repo — that is the point, since the analyzer must work against a
+repo you have not booted. Two of them are real Rails apps that boot on PostgreSQL and
+cover both isolation regimes; the specs needing them skip rather than fail when they
+are not prepared:
+
+```bash
+cd spec/fixtures/apps/rails71_basic && bundle install && RAILS_ENV=test bundle exec rails db:schema:load
+```
+
+`spec/equivalence/host_equivalence_spec.rb` is the one to read first. It holds the
+probe process and the spec process to the same answer across all six axes they could
+disagree on, and each fixture is configured to disagree with the plan so that
+agreement cannot happen by accident.
+
+## License
+
+MIT

data/exe/pinspec

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "pinspec"
+
+Pinspec::CLI.start(ARGV)