constable-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a0630c0ca6e000d33e21515a284616186d1939531ba5f5e9c5c61882d6dc9ec
+  data.tar.gz: 10fcc4a75763bec06db7049bd3815214e1320ecdb4f3ad2780ef0497b8f8af6b
+SHA512:
+  metadata.gz: 9a823bc22286ffaff8ab4c29f4f357ba40af37e423a9c6d1cab82382edf5d19c0ca0fae9796c0171f256bab6bdef93c9e2f14a65dd9a57e6e49e2cede204e959
+  data.tar.gz: 0c043327dc97ace117a1dae5919c9b066df22059deafa5a422066e96b3abafc6f67df7e33f911f68a8eb314b3cca6e7bab0150c7d91c3d6b26f92482baee8b0e

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release.
+
+### The case file
+
+- `Constable::Case` with the full case-file DSL: `investigate`, `witness`, `briefing`,
+  `docket`, and the `tier` macro.
+- `investigate` is a registration DSL, not a method definition — every investigation runs
+  in its own fresh instance, so no two tests can reach each other.
+- `witness` memoizes per test, never per process.
+- No `before(:all)` equivalent exists, deliberately.
+- Shared behavior across files is a plain Ruby module you `include` — no shared-examples DSL.
+
+### Rails
+
+- A railtie registers Constable as the app's generator test framework, so
+  `rails generate scaffold` writes cases rather than Minitest files. Every generator Rails
+  hooks is covered, and no fixtures are generated — a `witness` replaces them.
+- `Constable::RailsSupport::Integration` and `::System` give the tier base classes the
+  request stack and Capybara respectively.
+- `Constable::Case` answers to minitest's `setup`/`teardown` macros and lifecycle hooks, so
+  the Rails ecosystem's testing modules compose with it. `briefing` remains the primary API.
+
+### Adoption
+
+- `Constable::ColdCase::RSpec` and `Constable::ColdCase::Minitest` run an existing spec or
+  test file completely untouched, through its own real engine, feeding results into
+  Constable's reporting, flake history and CI gate alongside native cases.
+- Zero-file-change adoption via `cold_cases:` globs in `.constable/config.yml`.
+- `constable import --from=rspec|minitest` (reopen, verbatim) and the opt-in
+  `constable modernize PATH` AST rewrite into the native DSL.
+- `rails generate constable:install` writes `test/case_helper.rb`, `test/support/`,
+  `.constable/config.yml`, and the optional `:cold_case` Gemfile group.
+
+### Strictness
+
+- `unsafe { }` escape hatch — always warns, never silent, with `file:line` and the reason.
+- `rubocop-constable` companion gem: `NoSleep`, `NoUnfrozenTime`, `NoNetworkWithoutStub`,
+  `NoSharedMutableState`, `NoConditionalAssertions`, `NoRetryHelpers`, `UnsafeBlockVisibility`
+  — scoped to native cases only; cold cases are exempt by design.
+
+### Anti-flake
+
+- Random order every run with a printed, replayable seed.
+- Order-dependency detection in CI.
+- State-leak check after each native investigation.
+- Flake history keyed by a **content hash of the investigate block**, so renaming a class,
+  rewording a description or moving a file carries history over untouched.
+- Rename detection with `auto_relink` and `constable history relink OLD NEW`.
+- Jail, parole and parole-violation tracking for legacy red suites.
+- Warrants — automatic flaky detection that answers "is this failure even real."
+
+### Speed
+
+- Boot tiers via base classes, with path-based inference as a fallback.
+- Parallel workers, load-balanced by a cached per-test duration index.
+- Git-diff-based local test selection; `--full` for everything.
+
+### Watching the suite
+
+- `constable watchlist` — jailed, paroled and warranted tests in one view.
+- `constable status` — the trend view: how much of the suite is still running as cold
+  cases and whether that number is moving, the recent runs, and the ten slowest tests
+  historically.
+
+### Output
+
+- Live glyph stream, then a summary that leads with what is most urgent: parole
+  violations, failures, warnings, slowest.
+- Failures carry their own context, point at the `investigate` line rather than framework
+  internals, and print a ready-to-paste rerun command with the seed.
+- stdout is results only; `Rails.logger` and SQL go to `log/test.log`, streamed with `--verbose`.
+
+### Coverage
+
+- Diff-based coverage gate — only lines changed in the current diff are held to the
+  threshold. `constable beat` for the full picture, `--html` for a browsable report.
+
+[Unreleased]: https://github.com/Ray-Hughes/constable/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Ray-Hughes/constable/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ray Hughes
+
+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,515 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Ray-Hughes/constable/main/docs/assets/logo.png" alt="Constable" width="200">
+
+# Constable
+
+**A strict Rails testing framework where fast and non-flaky are structural, not disciplinary.**
+
+[![Gem Version](https://img.shields.io/gem/v/constable-rails?color=1f6feb&label=constable-rails)](https://rubygems.org/gems/constable-rails)
+[![CI](https://github.com/Ray-Hughes/constable/actions/workflows/ci.yml/badge.svg)](https://github.com/Ray-Hughes/constable/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-D30001)](https://rubyonrails.org)
+[![License](https://img.shields.io/badge/license-MIT-black)](LICENSE.txt)
+
+[Install](#installation) · [Quick start](#quick-start) · [Documentation](#documentation) · [Contributing](#contributing)
+
+</div>
+
+---
+
+```ruby
+class UsersController::CreatesUserCase < IntegrationCase
+  witness(:valid_params) { { user: { email: "a@b.com", password: "secret123" } } }
+
+  briefing { stub_network! }
+
+  investigate "creates a user with valid params" do
+    freeze_time
+
+    post users_path, params: valid_params
+
+    attest(response).to be_created
+    attest(User).to exist(email: "a@b.com")
+  end
+end
+```
+
+Most suites are fast and reliable because a team keeps them that way by hand. Constable
+makes it structural instead — isolation you cannot opt out of, nondeterminism caught by a
+linter instead of by CI, and an adoption path that never asks you to rewrite anything.
+
+> **Installed as `constable-rails`.** The name `constable` was claimed on RubyGems in 2011
+> by an unrelated, long-abandoned gem. That is the only thing the suffix affects —
+> everything you actually type is `constable`: the module, the CLI, the config directory,
+> the generators.
+
+## Table of contents
+
+- [Why](#why)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Documentation](#documentation)
+  - [The DSL](#the-dsl)
+  - [Tiers](#tiers-are-base-classes-not-magic)
+  - [Matchers](#matchers)
+  - [Shared behavior](#shared-behavior-is-just-ruby)
+  - [Rails generators](#rails-generators)
+  - [Adopting an existing suite](#adopting-an-existing-suite)
+  - [Escape hatches](#escape-hatches-always-visible)
+  - [The linter](#the-linter)
+  - [Jail, parole and warrants](#jail-parole-and-warrants)
+  - [Identity survives renames](#identity-survives-renames)
+  - [Command reference](#command-reference)
+  - [Output](#output)
+  - [The blotter](#the-blotter)
+  - [Configuration](#configuration)
+- [Contributing](#contributing)
+- [Reporting a problem](#reporting-a-problem)
+- [License](#license)
+
+## Why
+
+1. **Isolation is non-negotiable in native code.** No class-level shared state, no
+   `before(:all)` equivalent. Every native test gets a clean transaction and a clean
+   object graph.
+2. **Nondeterminism is caught by the linter, not discovered in CI.** Bare `sleep`,
+   unfrozen `Time.now`, and unstubbed network calls are lint errors before they are flakes.
+3. **Adoption never requires a rewrite.** A whole existing RSpec or Minitest file runs
+   completely untouched from day one. Strictness applies to new code — it is not a
+   precondition for installing the gem.
+4. **Every escape hatch is visible.** An `unsafe` block, a cold case, a jailed test — none
+   are ever silent. They are reported every run until someone deals with them.
+5. **Fast is the default, not an opt-in.** Boot tiers, parallel workers and git-diff test
+   selection all ship in the base gem.
+
+## Requirements
+
+| | Minimum | Notes |
+|---|---|---|
+| **Ruby** | **3.1** | Parallel workers use `fork`, so they are unavailable on Windows and JRuby; those platforms fall back to serial automatically. |
+| **Rails** | **7.0** | Tested against 7.1 and 8.1. |
+
+Constable pulls in five gems, all of them small and already present in most Rails apps:
+
+| Gem | Version | What needs it |
+|---|---|---|
+| `activesupport` | `>= 7.0` | `freeze_time` / `travel_to` delegate to it when it's there |
+| `railties` | `>= 7.0` | the generators and the railtie that registers Constable as your test framework |
+| `thor` | `>= 1.2` | the `constable` CLI |
+| `sqlite3` | `>= 1.6` | the blotter — flake history, the jail docket, warrants |
+| `parser` | `>= 3.1` | the AST rewrite behind `constable modernize` |
+
+Your app's own database is untouched by any of this: the blotter is a separate SQLite file
+Constable owns. See [The blotter](#the-blotter).
+
+Nothing else is required. These are all optional, and only if you want the feature:
+
+| Optional | For |
+|---|---|
+| `rubocop-constable` | the linter — the seven cops that catch nondeterminism at edit time |
+| `rspec-rails` / `minitest` | cold cases, if you are adopting an existing suite |
+| `capybara` + a driver | the `:system` tier |
+| `pg` / `mysql2` | pointing the blotter at Postgres or MySQL instead of SQLite |
+
+## Installation
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "constable-rails"
+  gem "rubocop-constable", require: false
+end
+```
+
+```console
+$ bundle install
+$ rails generate constable:install
+```
+
+That writes `test/case_helper.rb`, `test/support/`, `.constable/config.yml`, a `.rubocop.yml`
+snippet, and a worked example case so `constable test` does something immediately.
+
+## Quick start
+
+```console
+$ constable test              # only what your current git diff touches
+$ constable test --full       # everything. this is what CI runs
+$ constable test path/to/case.rb:12
+```
+
+## Documentation
+
+### The DSL
+
+The vocabulary is the API, not decoration.
+
+| Constable | Replaces | Notes |
+|---|---|---|
+| `Constable::Case` | `describe` / `TestCase` | One file, roughly one subject under test |
+| `investigate "..." do` | `it` / `def test_` | A plain string — punctuation and interpolation are fine |
+| `witness(:name) { }` | `let` | Memoized **per test**, never per process |
+| `briefing do ... end` | `before` / `setup` | Runs before every investigation. There is no `before(:all)` |
+| `docket "..." do ... end` | nested `describe` | Grouping that introduces no shared state |
+| `attest(x).to matcher` | `expect(x).to` | Sugar over `assert_*` primitives, which are always available too |
+
+`investigate` is a **registration DSL, not a method definition.** Each block runs in its own
+fresh instance, fully isolated from every other one.
+
+```ruby
+class UsersController::CreatesUserCase < IntegrationCase
+  docket "as an admin" do
+    briefing { sign_in(:admin) }
+
+    investigate "creates a user with valid params" do
+      post users_path, params: valid_params
+      attest(response).to be_created
+    end
+  end
+
+  docket "as a guest" do
+    investigate "is redirected to sign in" do
+      post users_path, params: valid_params
+      attest(response).to redirect_to(sign_in_path)
+    end
+  end
+end
+```
+
+### Tiers are base classes, not magic
+
+```ruby
+# test/case_helper.rb
+class UnitCase < Constable::Case
+  tier :unit
+end
+
+class IntegrationCase < Constable::Case
+  include Constable::RailsSupport::Integration
+  tier :integration
+end
+
+class SystemCase < Constable::Case
+  include Constable::RailsSupport::System if defined?(Capybara)
+  tier :system
+end
+```
+
+Subclass whichever fits. Path-based inference (`test/cases/models/**` → `:unit`) still works
+as a fallback, but ordinary inheritance is the recommended pattern — nothing to infer.
+
+`RailsSupport::Integration` is what gives a case `get`/`post`, `response` and your app's URL
+helpers; `RailsSupport::System` gives it Capybara and `driven_by`. `UnitCase` gets neither,
+deliberately — that is the tier that boots without them. The installer writes all three.
+
+Rails' testing modules expect minitest's lifecycle, so `Constable::Case` also answers to the
+`setup` and `teardown` class macros. `setup` is an exact synonym for `briefing` and exists so
+those modules compose — **`briefing` is still the way to write setup.**
+
+### Matchers
+
+```ruby
+# test/support/matchers.rb
+Constable::Matchers.define(:be_created) { |response| response.status == 201 }
+Constable::Matchers.define(:exist) { |model_class, attrs| model_class.exists?(attrs) }
+```
+
+Built in: `eq`, `eql`, `include`, `match`, `raise_error`, `have_attributes`, `exist`,
+`be_created`, `redirect_to`, `have_http_status`, `change`, plus `be_a`, `be_nil`, `be_empty`,
+`be_truthy`, `be_falsey` and a `be_*` / `have_*` predicate fallback. Plain `assert_*` and
+`refute_*` primitives are always available alongside `attest`.
+
+### Shared behavior is just Ruby
+
+There is deliberately no shared-examples mechanism. Reuse across files is a module:
+
+```ruby
+# test/support/authenticatable.rb
+module Authenticatable
+  def sign_in(user)
+    post session_path, params: { email: user.email, password: "password" }
+  end
+end
+```
+
+`include Authenticatable` in any case. Ruby's own composition tools are more flexible than a
+parallel DSL that does the same job.
+
+### Rails generators
+
+`rails generate` asks whatever is registered as the app's test framework what a test file
+looks like. Constable registers itself, so scaffolds produce cases rather than Minitest
+files for a framework you replaced.
+
+```console
+$ rails generate scaffold Post title:string
+      create  test/cases/controllers/posts_controller_case.rb
+      create  test/cases/system/posts_case.rb
+```
+
+Every generator Rails hooks is covered — `model`, `controller`, `scaffold`, `integration_test`,
+`system_test`, `mailer`, `job`, `helper`, `channel`, `mailbox`, `generator`, `resource` — each
+writing a case that subclasses the right tier base class.
+
+No fixtures are generated, deliberately: a `witness` builds exactly what one investigation
+needs and throws it away with it. A factory gem registered as your `fixture_replacement`
+still gets its turn.
+
+### Adopting an existing suite
+
+Nothing gets rewritten. **Cold cases** run your original file through its own real engine —
+RSpec or Minitest — and feed pass/fail/timing into Constable's reporting, flake history and
+CI gate alongside native cases.
+
+**One line changes.** The file body is untouched:
+
+```ruby
+class LegacyUsersSpec < Constable::ColdCase::RSpec
+  describe UsersController do
+    it "creates a user" do
+      post users_path, params: valid_params
+      expect(response).to have_http_status(:created)
+    end
+  end
+end
+```
+
+**Or nothing changes at all** — match the path in config:
+
+```yaml
+cold_cases:
+  - spec/controllers/**/*_spec.rb
+```
+
+```console
+$ constable import --from=rspec        # reopen everything, verbatim
+$ constable modernize spec/controllers/users_controller_spec.rb --alongside
+```
+
+`modernize` converts `describe`/`it` → `Constable::Case`/`investigate`, `let` → `witness`,
+`before` → `briefing`, `expect` → `attest`, and `def test_foo` → `investigate "foo"`. It
+**flags `before(:all)` and `let!` rather than converting them** — those need a human decision —
+and leaves custom matchers and `shared_examples` alone, logging everything to
+`constable_modernize_report.md`. It writes nothing unless you ask it to.
+
+Native and cold cases run side by side in one `constable test`. No big-bang cutover.
+
+### Escape hatches, always visible
+
+```ruby
+investigate "times out after thirty seconds" do
+  unsafe { sleep(0.1) } # testing an actual timeout path, not a code smell
+  attest(subject).to have_timed_out
+end
+```
+
+Every `unsafe` emits a warning with its `file:line` and that adjacent comment as the reason.
+One warning per cold-case *file*, one per `unsafe` occurrence. Warnings never fail the build
+by default — `fail_on_warnings: true` opts CI into enforcing a downward trend — but they are
+never silent either.
+
+### The linter
+
+`rubocop-constable` is scoped to native cases only; cold cases are exempt by design.
+
+| Cop | Catches |
+|---|---|
+| `NoSleep` | bare `sleep` outside `unsafe` |
+| `NoUnfrozenTime` | `Time.now` / `Date.today` / `Time.current` outside `freeze_time`/`travel_to` |
+| `NoNetworkWithoutStub` | HTTP calls without `stub_network!` |
+| `NoSharedMutableState` | class variables and globals mutated across investigations |
+| `NoConditionalAssertions` | `if`/`else` branching around assertions |
+| `NoRetryHelpers` | any retry/eventually pattern |
+| `UnsafeBlockVisibility` | an `unsafe` block with no comment explaining why |
+
+### Jail, parole and warrants
+
+A large red legacy suite has an on-ramp. Run once in jail mode for a clean baseline, then
+work the docket down.
+
+```console
+$ constable test --jail          # failures get jailed instead of failing the build
+$ constable jail                 # the docket: reason, file:line, date jailed
+$ constable jail run             # re-run jailed tests sequentially
+$ constable jail parole PATH:LINE
+$ constable jail release PATH:LINE
+```
+
+Jailing isn't hiding — it swaps "blocks the build" for "tracked and skipped." Jailed tests are
+always their own summary category, never folded into passed, and their `briefing`/`witness`
+setup still runs so setup rot surfaces immediately.
+
+**Parole** is "probably fixed, not fully trusted yet." A paroled test runs normally but is
+watched: one failure is an immediate violation straight back to jail, and `parole_period`
+consecutive clean runs (default 10) auto-releases it. `jail run` never auto-releases on a
+pass — a single green run doesn't prove anything.
+
+**Warrants** answer a different question — not "does this block the build" but "is this
+failure even real." With warrants on, a failing test is rerun in isolation `warrant_retries`
+times (default 5). Fails every retry, it's a genuine failure. Passes even once, it's flaky
+rather than broken: a warrant is written to the blotter, never to your source, and the result
+stops blocking the build while staying loudly visible.
+
+```console
+$ constable warrants
+$ constable warrants release PATH:LINE
+$ constable watchlist    # everything under supervision: jailed, paroled, warranted
+$ constable status       # trend: native-vs-cold %, recent runs, slowest historically
+```
+
+### Identity survives renames
+
+Each test's key is a **content hash of its `investigate` block body**, whitespace-normalized.
+Class name, description and file are stored alongside purely as a display label.
+
+- Rename the class, reword the description, move the file → hash untouched, history carries over.
+- Change what the test actually *does* → hash changes, history starts fresh. Correct, not a limitation.
+- Renamed *and* tweaked in one commit? Constable notices an old test vanishing as a similar
+  new one appears and suggests `constable history relink OLD NEW`. Set `auto_relink: true` to
+  confirm high-confidence matches automatically.
+
+### Command reference
+
+| Command | Runs |
+|---|---|
+| `constable test` | Everything, git-diff-scoped locally |
+| `constable test --full` | The whole suite. CI always uses this |
+| `constable test PATH[:LINE]` | One file, or one investigation at that line |
+| `constable test --unsafe` | Cold cases only |
+| `constable test --jail` | The full run, in jail mode |
+| `constable jail [run\|parole\|release]` | The docket |
+| `constable warrants [release]` | Outstanding warrants |
+| `constable watchlist` | Everything under supervision right now |
+| `constable status` | How the suite is doing over time |
+| `constable beat [--html]` | Coverage: overall %, per-file, the unpatrolled list |
+| `constable history relink OLD NEW` | Carry history across a real body change |
+| `constable import --from=rspec` | Adopt an existing suite as cold cases |
+| `constable modernize PATH` | Opt-in AST rewrite into the native DSL |
+
+Flags: `--full --unsafe --jail --warrants --coverage --seed N --workers N --verbose --tier T --no-color`.
+
+Order is randomized every run for native cases, with the seed printed and replayable via
+`--seed`. Cold cases keep their own engine's order. Workers run in parallel by default,
+load-balanced by a cached per-test duration index.
+
+### Output
+
+stdout is reserved for results. `Rails.logger`, SQL and request/response logging go to
+`log/test.log`; `--verbose` streams it back for active debugging.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  CONSTABLE            482 tests · 3 cases · 12.4s
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓ 478 passed   ✗ 2 failed   ⛓ 2 jailed (1 parole violation)   ◑ 1 on parole   ⚖ 1 warrant issued   ⚠ 3 warnings   ◐ 92% covered
+
+  FAILURES
+  ────────
+  ✗ SessionsCase
+    "expires after inactivity"
+    spec/cases/sessions_case.rb:12
+
+    Expected response to be :created, got :unprocessable_entity
+
+    Response body:
+      { "errors": ["Email has already been taken"] }
+
+    Rerun just this test:
+      constable test spec/cases/sessions_case.rb:12 --seed 8841
+```
+
+Sections print worst-to-least-urgent: parole violations, failures, warnings, slowest.
+Failures carry their own context and point at your `investigate` line, not at framework
+internals.
+
+### The blotter
+
+Flake history, the jail docket and warrants live in a store Constable owns entirely — by
+default a self-contained `.constable/constable.sqlite3` in WAL mode. Never your app's
+database: native cases roll back their transaction and would roll this data back with it,
+`:unit`-tier runs skip booting the DB stack for speed, and the workload is a handful of
+tables that doesn't need a client-server database.
+
+Teams who need one queryable store across many CI machines can point it elsewhere — always a
+separate connection from the app's own:
+
+```yaml
+storage:
+  adapter: postgres
+  url: postgres://user:pass@host/constable_metadata
+```
+
+### Configuration
+
+```yaml
+# .constable/config.yml
+cold_cases:
+  - spec/controllers/**/*_spec.rb
+
+storage:
+  adapter: sqlite                # sqlite (default) | postgres | mysql
+  path: .constable/constable.sqlite3
+
+warrants: false                  # opt-in flaky detector
+warrant_retries: 5
+auto_relink: false
+
+parole_period: 10                # consecutive clean runs to auto-release
+
+coverage: false
+coverage_threshold: 90           # diff-based — only lines changed in the current diff
+coverage_html: false
+
+fail_on_warnings: false
+parallel_workers: auto
+
+tiers:                           # fallback inference; base classes are primary
+  unit: "test/cases/models/**/*"
+  integration: "test/cases/controllers/**/*"
+  system: "test/cases/system/**/*"
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/Ray-Hughes/constable>.
+
+```console
+$ git clone git@github.com:Ray-Hughes/constable.git
+$ cd constable
+$ bin/setup
+$ bundle exec rake test      # the framework's own suite
+$ bundle exec rake cops      # the RuboCop extension's suite
+$ bundle exec rubocop        # lint
+```
+
+The repo holds two gems: `constable-rails` at the root, and `rubocop-constable` in its own
+directory with its own gemspec and suite. `docs/ARCHITECTURE.md` is the interface contract
+between components and is worth reading before a substantial change; `docs/SPEC.md` is the
+product spec.
+
+A few house rules, so a change lands cleanly:
+
+- **Constable's own suite is Minitest**, not Constable — it cannot test itself before it
+  works. Add tests under `test/unit/` or `test/integration/`.
+- **New behavior needs a test that would fail without it.** Several of the nastiest bugs in
+  this gem were invisible to unit tests and only appeared when the real binary ran against a
+  real Rails app; an integration test is often the honest one.
+- **Keep `rake test` and `rubocop` green.** CI runs both on Ruby 3.1, 3.2 and 3.3.
+- Comments explain *why*, not *what*.
+
+## Reporting a problem
+
+Please open a [GitHub issue](https://github.com/Ray-Hughes/constable/issues). Include:
+
+- what you ran, and the full summary block it printed
+- the seed, so the order is replayable (`constable test --seed N`)
+- your Ruby and Rails versions, and whether the case is native or a cold case
+
+If a test behaves differently alone than in a full run, say so explicitly — that is an
+order-dependency bug and Constable has machinery specifically for it.
+
+## License
+
+[MIT](LICENSE.txt).

data/exe/constable

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "constable"
+require "constable/cli"
+
+Constable::CLI.dispatch!(ARGV)