rspec-tracer 1.2.4 → 2.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a5c7bccaf770c4b630f3aafbe2965e7a88eebf912d4e5f331eb6001613e0559
-  data.tar.gz: cd2c8bb4ea28fa5c70807e8ca7e9249e16a7313f9e17662e3b76d20cc26a91ab
+  metadata.gz: 04d2e3c76b8351f5f71f93cd722af23975f80da067f19970471455b3b2ed16aa
+  data.tar.gz: 0ab86f0d744275db42ed0d355d5781d25a6f65ed49a76fcd70d3df1acd7e01b4
 SHA512:
-  metadata.gz: 2a5889f5a017183e40e63b56c10b6abf2309dff7b18ca941c2f36552e947b508ca3ac144290143a44b2bf78c7f76569eba96d1d580f69eb9a2d2a138e3c004ba
-  data.tar.gz: 79ff93be56d9f9bee3c397b0d78ef0cb4114b5c746879d9afcbf6372d2eb55a8950b75f772372c78aaea3852a12a0750a1098758cf343c41c9caa86b485ac054
+  metadata.gz: e802e4c67a41d1d1ebd16df2fd4ee874f0993678097563f38b5bd3e443024662040547df140dd45196c0e81e7d510ecfe79dbf4a3e01ab1a4685f380f9ec829f
+  data.tar.gz: 72435a0282503ff2c90b6b80168fb810bd48412bc162043b4d70780b35f74478fc5236c43710bb9e948657b2c6c17734a59406fc617cb712eaba7e1a3c2e4dfb

data/CHANGELOG.md

@@ -1,181 +1,208 @@
-## [1.2.4] - 2026-05-17
+## [2.0.0.pre.1] - 2026-05-06
 
-### Fixed
-
-- **`example_id` was unstable across runs — a long-standing bug since
-  v1.0.0.** `RSpecTracer::Example.from` built the MD5 identity hash
-  over a payload that included `example_group.name` (RSpec's
-  generated class name, which carries a load-order-dependent `_2` /
-  `_3` suffix when two spec files share a `describe` name) and the
-  example's `line_number`. The same example got a different id
-  depending on rspec's file load order — silently thrashing the
-  cache and breaking the always-re-run guarantees for failed,
-  pending, and flaky examples. A no-op blank-line edit above the
-  example flipped the id with the same effect.
-
-  The digest now uses a stable subset: the describe block's
-  *description* string (the user-supplied text, not RSpec's
-  generated class name), the example's `description`,
-  `full_description`, `shared_group` inclusion locations with the
-  trailing `:LINE` stripped, and `file_name`. `line_number` /
-  `rerun_file_name` / `rerun_line_number` still ride along in the
-  returned Hash for the HTML and JSON reporters' location columns,
-  but no longer enter the digest. Contract: **rename = new identity;
-  restructure = same identity.**
-
-  Unnamed examples (`it { }`, `specify { }`, `example { }`) needed
-  an extra step. RSpec's pre-run `description` for an unnamed
-  example is the line-bearing `"example at <path>:<line>"`
-  fallback, which would have re-leaked the line number straight
-  into the digest. The digest substitutes a line-independent
-  positional discriminator: the example's ordinal among the
-  *unnamed* examples of its group. Stability is preserved across
-  blank-line edits and across adding or renaming *named* siblings;
-  reordering the unnamed examples re-keys them (the documented
-  trade-off — give the example an explicit description for a fully
-  reorder-stable id).
-
-  **Upgrade note**: the cache file format is unchanged, so a v1.2.3
-  cache loads cleanly through v1.2.4 code. But every cached
-  `example_id` was computed against the old payload and the new
-  lookups will not match them, so the first run after upgrade
-  treats every example as `:no_cache` and re-runs the full suite.
-  Warm caches resume from the second run onward.
-
-  Surfaced by 2.0.0.pre.1 field testing against third-party Rails
-  apps. Fixed upstream in
-  [#209](https://github.com/avmnu-sng/rspec-tracer/pull/209) and
-  [#211](https://github.com/avmnu-sng/rspec-tracer/pull/211).
-
-- **`RSpecTracer.start` crashed when the user pre-started
-  `::Coverage`.** Users opting into branch coverage typically call
-  `Coverage.start(lines: true, branches: true)` before loading
-  rspec-tracer. The tracer's `setup_coverage` then called bare
-  `::Coverage.start` with no `running?` guard, raising
-  `RuntimeError: coverage measurement is already setup` and taking
-  the tracer down at boot.
-
-  Add a `Coverage.running?` predicate guard before the start call,
-  plus a defensive `RuntimeError` rescue with a `logger.warn` for
-  the case where the predicate returns false but `start` still
-  raises. Graceful degradation: coverage measurement is skipped
-  with a visible warn, the rest of the tracer pipeline continues.
-
-  Partial port of upstream
-  [#207](https://github.com/avmnu-sng/rspec-tracer/pull/207); the
-  `coverage_modes` config DSL half is 2.0-only.
-
-- **`remote_cache` success paths were silent at default log level.**
-  `RemoteCache::Cache#download` and `#upload` returned without
-  emitting anything after the underlying AWS calls succeeded, so a
-  successful `rake rspec_tracer:remote_cache:download` produced
-  zero output. Users couldn't tell from CI logs whether the cache
-  was actually restored or whether the run was cold.
-
-  Emit a single `RSpecTracer.logger.info` line on each operation's
-  success path: `"rspec-tracer remote_cache: restored cache from
-  <sha>"` on download, `"rspec-tracer remote_cache: uploaded cache
-  to <ref>"` on upload.
-
-  Partial port of upstream
-  [#201](https://github.com/avmnu-sng/rspec-tracer/pull/201); the
-  cross-branch-fallback qualifier is specific to 2.0's multi-tier
-  cache model and not applicable here.
-
-### Changed
+The first pre-release of the 2.0 line. Architecture rewrite around
+the input-taxonomy mental model documented in
+[`ARCHITECTURE.md`](ARCHITECTURE.md): every test is a pure function
+of its inputs; tracking is input identification; cache invalidation
+is input-digest mismatch.
 
-- **`rspec-tracer.gemspec` now declares `rubygems_mfa_required`** so
-  RubyGems enforces MFA on every publish. Packaging metadata only;
-  no behaviour change for users of the gem. Mirrors upstream
-  [#214](https://github.com/avmnu-sng/rspec-tracer/pull/214).
+The 1.x cache is not readable by 2.0 — first run on the new version
+is cold, then warm caches resume. Existing CI integration (`rake
+rspec_tracer:remote_cache:download` / `:upload`, the env vars,
+the `rspec_tracer_cache/` / `rspec_tracer_coverage/` /
+`rspec_tracer_report/` directory contracts) is preserved bit-for-bit.
 
-- **`.github/workflows/release.yml` tag-trigger pattern tightened
-  to the strict `'v[0-9]+.[0-9]+.[0-9]+'` form** (1.x is
-  final-release only). The previous loose `'v*.*.*'` form would
-  have matched 4-segment shapes like `v2.0.0.rc.1` accidentally
-  because `*` greedy-matches dots; the strict per-segment digit
-  class rejects any non-digit. Documentation block above the
-  pattern explains the GHA filter-pattern flavor for future
-  maintainers. Workflow-only; no user-visible change.
+### Added
 
-## [1.2.3] - 2026-05-06
+- **Pluggable storage backends.** `storage_backend :json` (default,
+  preserves 1.x JSON layout) or `storage_backend :sqlite` (single-
+  file SQLite database; MRI only — JRuby falls back to `:json` with
+  a one-time warn). The 10-file per-run JSON layout (`last_run.json`
+  + `<run_id>/{all_examples,duplicate_examples,interrupted_examples,
+  flaky_examples,failed_examples,pending_examples,skipped_examples,
+  all_files,dependency,examples_coverage}.json`) is unchanged.
+- **Pluggable remote-cache backends.** `remote_cache_backend :s3`
+  (preserves the 1.x S3 layout including `awslocal` / LocalStack
+  support), `:local_fs` (filesystem-backed; no S3 needed), or
+  `:redis` (with optional per-key TTL + `<prefix>:pr_branches`
+  sidecar SADD on PR-tier uploads for ops dashboards).
+- **Per-example `tracks:` DSL.** Annotate any describe / context /
+  example with `tracks: { files: 'app/policies/**/*.rb', env:
+  'ROLE_CONFIG' }` to declare extra inputs the tracker can't auto-
+  observe — config files baked at boot, env-var branches, and
+  similar. `:files` accepts a string glob or array; `:env` accepts a
+  literal name, array, or single-wildcard pattern (`'RAILS_*'`,
+  `'*_TOKEN'`, `'*'`). Cascade unions parent + child without
+  clobbering.
+- **`track_env(*names)` config-level DSL** for env vars every test
+  depends on (`AUTH_TOKEN`, `DATABASE_URL`, `RAILS_ENV`). Same
+  wildcard syntax as the per-example `tracks: { env: ... }`.
+  Persists as `env_snapshot.json` (concrete keys only, no pattern
+  leakage).
+- **`track_files(*globs)` config-level DSL** for files every test
+  depends on (`Gemfile.lock`, schema, locale catalogs).
+- **Rails preset** via `track_rails_defaults` — auto-attaches the
+  common Rails-side declared globs (views, locales, fixtures,
+  factories, helpers, config). `track_rails_defaults except:
+  [:views, :schema]` opts specific globs out so framework-event
+  subscribers (`render_template.action_view` for views; the opt-in
+  `sql.active_record` observer enabled by
+  `track_ar_schema_notifications` for `db/schema.rb`) attribute
+  them per-example instead.
+- **Auto-detection of Rails** at start time; the engine attaches
+  `ActionView` template + `ActiveRecord` schema (when opted in)
+  notification observers automatically when `::Rails::VERSION` is
+  defined.
+- **`bin/rspec-tracer` CLI** with five sub-commands:
+  `doctor` (config + environment diagnosis, schema-version + remote-
+  cache reachability + AR-schema-narrow checks), `cache:info`
+  (size, last run, invalidation stats), `cache:clear` (rm cache
+  dirs), `report:open` (open the HTML report in the default
+  browser), `explain <example_id>` (show why a given example is
+  scheduled to run or skip). The CLI is opt-in for local-dev
+  convenience; the `rake rspec_tracer:remote_cache:*` tasks remain
+  first-class for CI integration.
+- **Boot-time warns** for two common user-trust traps:
+  - SimpleCov loaded but not started before `RSpecTracer.start`
+    (load-order is part of the documented contract; the warn
+    surfaces it instead of silently bolting onto a Coverage already
+    in flight).
+  - `track_ar_schema_notifications` enabled with
+    `use_transactional_fixtures` defaulting to true (per-example
+    BEGIN/COMMIT fires `sql.active_record` and attributes
+    `db/schema.rb` to every AR-touching example; the warn points
+    at the README "Narrow AR-schema attribution" guidance).
+- **`.rspec-tracer` DSL typo `did you mean?` suggestions** at config
+  load — typos like `track_filez` raise `InvalidUsageError` with a
+  pointer at `track_files`.
+- **Rails 8.0 CI-gated support** (Ruby 3.2+ required; Rails 8.0
+  dropped Ruby 3.1 support upstream). `jruby-9.4 × Rails 8.0` is
+  unsupported (no `activerecord-jdbcsqlite3-adapter ~> 80.0`
+  upstream).
+- **Schema-version field** in `last_run.json` for explicit
+  cross-version cache validation. Cache-shape changes bump the
+  field; mismatched caches refuse-to-load with an info-level "cold
+  run" log line.
+- **`docs/CI_RECIPES.md`** translating the
+  [`.github/workflows/example-tracer-cache.yml`](.github/workflows/example-tracer-cache.yml)
+  GitHub Actions cache pattern to CircleCI / GitLab CI / Buildkite
+  / Heroku CI. The 4-component cache key (`runner.os` +
+  `.ruby-version` + `lib/rspec_tracer/version.rb` + Gemfile-hash)
+  translates 1:1 across providers; only the YAML envelope is
+  GHA-specific.
+- **Coexistence smokes** for `rspec-retry`, `rspec-rerun`, and
+  `knapsack`. All three compose with rspec-tracer's `Module#prepend`
+  chain on `RSpec::Core::Runner` / `Reporter` without override.
+- **`bin/rspec-tracer doctor` reachability checks** for the
+  configured remote-cache backend (S3 / Local-FS / Redis) — surfaces
+  misconfigured credentials / missing buckets / unreachable Redis
+  hosts at first invocation instead of mid-CI-run.
+- **HTML reporter** (committed build output, no `assets:precompile`
+  step on user installs) and **JSON reporter** (machine-readable,
+  for CI dashboards) alongside the existing terminal output. The
+  terminal line now includes a `by reason:` breakdown
+  (`12 Files changed · 3 Whole-suite invalidator changed · ...`)
+  and a cache size + delta suffix (`14.4 MiB; +6.7 KiB vs prev
+  run`).
 
-### Fixed
+### Changed
 
-- **Parallel-tests purge race when a sibling worker is still mid-flush**
-  — the elected worker trusted only `parallel_tests`'s pid-file barrier
-  (`ParallelTests.wait_for_other_processes_to_finish`), which under
-  specific scheduling/I/O timing on GHA Linux x86_64 can return while a
-  sibling's `parallel_tests_N/` dir hasn't fully flushed. The elected
-  then merged + purged, racing the in-progress sibling. Symptoms:
-  intermittent leftover `parallel_tests_N/` dir post-purge AND/OR
-  silently dropped peer caches in the merge.
-
-  Backport of upstream PR
-  [#168](https://github.com/avmnu-sng/rspec-tracer/pull/168). Adds a
-  filesystem barrier layered on top of the pid-file wait. Each worker
-  writes a `.rspec_tracer_boot` marker at `RSpecTracer.start` time and
-  a `.rspec_tracer_done` marker as the first step of its at_exit tasks;
-  the elected worker waits for every booted peer's `.done` to
-  materialize before proceeding to merge + purge. Two independent
-  signals (pid file + filesystem) must agree before the elected worker
-  declares the peer set stable. Bounded at 5 s with a graceful warn for
-  crashed peers — their dirs are purged regardless of completion state,
-  and the merge accepts whatever's on disk.
-
-## [1.2.2] - 2026-05-04
+- **Ruby ≥ 3.1** is the floor (1.x supported Ruby 2.5+). 3.2, 3.3,
+  3.4, 4.0 + JRuby 9.4 are CI-gated. Rails 7.0 / 7.1 / 7.2 / 8.0 +
+  RSpec 3.12 / 3.13 are CI-gated.
+- **SimpleCov branch coverage now works alongside rspec-tracer.**
+  The 1.x caveat ("SimpleCov would not report branch coverage
+  results even when enabled") is **no longer applicable** — the
+  coverage-stack rewrite decoupled rspec-tracer's line-only
+  emission from SimpleCov's branch-tracking. Users who turned
+  `enable_coverage :branch` off when adopting rspec-tracer 1.x can
+  re-enable in 2.0.
+- **Cache schema bump.** First run on 2.0 is cold; subsequent runs
+  return to warm.
+- **Coverage adapter** consolidated: a single
+  `Reporters::CoverageJsonReporter` owns `coverage.json` emission
+  (replacing the 1.x `CoverageReporter` + `CoverageWriter` pair).
+  Output shape preserved.
+- **Parallel-tests reporter behavior:** terminal / JSON / HTML
+  reports now emit ONCE at the merged top-level location after
+  `merge_snapshot!` runs, instead of per-worker (where
+  `purge_worker_dirs!` then removed them and left users with no
+  usable output). Per-worker emission was a pre-2.0 behavior bug.
 
 ### Fixed
 
+- **ERB template tracking via `render_template.action_view`** (closes
+  the issue behind upstream
+  [#66](https://github.com/avmnu-sng/rspec-tracer/issues/66)). The
+  Rails subscriber attributes rendered ERB partials to the example
+  that triggered the render.
+- **Phantom `metadata[:file_path]` graceful skip** (closes the issue
+  behind upstream
+  [#72](https://github.com/avmnu-sng/rspec-tracer/issues/72)). Specs
+  whose `metadata[:file_path]` doesn't resolve to a readable file
+  (gem-generated examples, deleted-between-runs files) now log
+  debug + skip dependency registration instead of raising.
 - **Default filter list now excludes rspec-tracer's own output
-  directories** (`rspec_tracer_cache/`, `rspec_tracer_coverage/`,
-  `rspec_tracer_report/`, and the `rspec_tracer.lock` file). Prior
-  versions did not exclude these paths, so any spec that read a tracer
-  cache file (typical for outer integration specs that assert on cache
-  state after a fixture subprocess run) had those paths attributed as
-  dependencies. The user-visible symptom was reverse-dependency reports
-  showing tracer-self paths as deps of unrelated specs, plus
-  spurious files-changed re-runs whenever the tracer rewrote its own
-  cache. Both `add_filter` and `add_coverage_filter` defaults updated.
-
-- **Carry-forward filter contract** — newly added filters now apply
-  uniformly to both fresh attribution AND prior-snapshot carry-forward.
-  Previously, `Cache#load_all_files_cache` and `load_dependency_cache`
-  read previous-run state without re-applying the current filter list.
-  A user adding a new filter mid-development saw the filter take
-  effect only for fresh attributions on cold runs; previously-cached
-  paths matching the new filter persisted in `all_files` and
-  `dependency` until the next cold run. Filter additions now take
+  directories** — `rspec_tracer_cache/`, `rspec_tracer_coverage/`,
+  `rspec_tracer_report/`, `rspec_tracer.lock`. Previously, tests
+  that read the tracer's own cache files (e.g. integration specs
+  asserting on cache state after a fixture subprocess run) got
+  those paths attributed as deps. The tracer's output is
+  regenerated every run by design and should never invalidate a
+  test. Both `add_filter` (dep graph) and `add_coverage_filter`
+  (coverage report) lists were updated.
+- **`add_filter` / `add_coverage_filter` now apply uniformly to
+  both fresh attributions AND prior-snapshot carry-forward.**
+  Previously, `Engine#seed_all_files_from_previous` and
+  `Engine#seed_graph_from_previous` seeded paths from the previous
+  run's snapshot WITHOUT re-applying the current filter list — so
+  a filter added between runs would NOT exclude already-cached
+  paths until a cold run wiped them. Filter additions now take
   effect on the very next warm run.
 
-## [1.2.1] - 2026-05-01
+### Deprecated
 
-### Fixed
+The 1.x configuration surface keeps working; each deprecated entry
+fires one `logger.warn` at first use pointing at the replacement.
+The deprecated values still resolve semantically. All four are slated
+for removal in 3.0.
+
+- **`reports_s3_path(uri)`** → use **`remote_cache_uri(uri)`**.
+- **`use_local_aws(bool)`** → use **`remote_cache_backend :s3,
+  local: true`**.
+- **`RSPEC_TRACER_REPORTS_S3_PATH`** → use
+  **`RSPEC_TRACER_REMOTE_CACHE_URI`**.
+- **`RSPEC_TRACER_USE_LOCAL_AWS`** → fold into
+  `remote_cache_backend` params.
+
+### Removed
 
-- **Parallel-tests merge silently dropped peer caches and left worker
-  directories behind** when the spawned-worker count exceeded
-  `ENV['PARALLEL_TEST_GROUPS']`. The merge + purge call-sites in
-  `lib/rspec_tracer.rb` (`merge_parallel_tests_reports`,
-  `merge_parallel_tests_coverage_reports`,
-  `purge_parallel_tests_reports`) iterated `1..ENV['PARALLEL_TEST_GROUPS']`
-  to construct per-worker directory names. But parallel_tests sets
-  `PARALLEL_TEST_GROUPS = num_processes.to_s` for each child, where
-  `num_processes` is the user-requested process count
-  (`Parallel.processor_count` by default) — not the actual worker
-  count. When `num_processes < spawned_worker_count` (e.g. when the
-  spec-count partition produces more non-empty groups than
-  `num_processes`, or shared-runner CPU detection drifts mid-run),
-  peer caches with `TEST_ENV_NUMBER` above the env bound were silently
-  dropped from the merge (warm-run skip decisions get made against
-  an under-sampled merged manifest) and left behind by the purge
-  (visible as straggler `parallel_tests_<N>/` directories under
-  `rspec_tracer_cache/`). The same gem behaviour was documented on
-  v1.1.1's `last_process?` fix
-  ([PR #101](https://github.com/avmnu-sng/rspec-tracer/pull/101)) but
-  the iteration call-sites kept the buggy bound. Each method now globs
-  the actual `parallel_tests_*` subdirectories under its base path,
-  making the merge + purge robust to whatever count parallel_tests
-  spawned. No cache format change.
+- **Cucumber feature-file integration suite.** Contributor-facing
+  only; users see no change. Replaced by RSpec subprocess
+  integration specs under `spec/integration/`. The `bundle exec
+  rake` legacy entry point is removed; `task` (Taskfile) is the
+  canonical dev loop.
+- **Ruby ≤ 3.0 and Rails ≤ 6.x support** (already dropped in 1.1.0;
+  re-stated here for clarity at the major boundary).
+- **Windows support** (no CI gate; never actively maintained).
+
+### Deferred to 2.1
+
+- **Per-example dependency attribution under Rails
+  `config.eager_load = true`.** When `eager_load = true` (Rails
+  default for CI tests to mirror prod), all `app/` files load at
+  boot and land in the boot-set; the whole-suite invalidator fires
+  on any `app/` edit, re-running every example. This is SAFE (never
+  misses a dep) but coarser than per-example attribution. The 2.1
+  enhancement will install a class-attribution mechanism (working
+  name: `track_class_attribution`) using `TracePoint(:class)` at
+  boot + `TracePoint(:call)` per example to trim the invalidator
+  scope to only examples that touched the changed file's class /
+  method surface. Opt-in by default; designed from scratch on the
+  user-shape problem (not a resurrection of any 1.x DSL name).
+  Today's escape hatches: set `config.eager_load = false` in test
+  env for full per-example precision, or use `tracks: { files:
+  '...' }` for per-example narrowing on specific groups.
 
 ## [1.2.0] - 2026-04-24