ripple_effect 0.1.0

data/docs/PUBLIC_LAUNCH_CHECKLIST.md

@@ -0,0 +1,105 @@
+# Public launch checklist
+
+RippleEffect v0.1 is a **private build**. Work through this before making the
+repository public or pushing to RubyGems.
+
+## 1. Name verification: do this first
+
+Everything else is wasted if the name is taken.
+
+- [ ] **RubyGems:** `gem owner ripple_effect` / check
+      `https://rubygems.org/gems/ripple_effect` returns 404. A registry lookup is
+      authoritative; a web search is not.
+      *(As of this build, `gem search -r ripple_effect` returns no results: but
+      re-verify immediately before reserving, and reserve the name promptly.)*
+- [ ] **GitHub:** the `ripple-effect` org or repo name is available.
+- [ ] **Existing tools:** search for other developer tools called "Ripple Effect"
+      or similar, in Ruby and beyond, to avoid a confusing collision.
+- [ ] **Trademark:** a basic search for conflicting marks in the software class.
+- [ ] **Domain and social handles**, if you want them.
+- [ ] Reserve the gem name with a `0.0.1` placeholder push once verified.
+
+Update every reference if the name changes: gemspec, `lib/ripple_effect/`,
+`exe/ripple-effect`, `.ripple-effect.yml`, module name, docs, and the
+`tmp/ripple_effect/` cache directory.
+
+## 2. Correctness and quality
+
+Verified locally on macOS (arm64) at the time of writing:
+
+- [x] `bundle exec rake` green. 435 examples, 0 failures.
+- [x] `bundle exec rake smoke` green. 9 checks.
+- [x] Suite green on Ruby 3.2.8, 3.3.10 and 3.4.7.
+- [x] Rails matrix green with Rails **actually installed**: 7.0.10, 7.1.6,
+      7.2.3.2, 8.0.5.1, 8.1.3.1.
+- [x] `gem build` emits zero warnings.
+- [x] Coverage above the bar. 95.9% line, 78.7% branch.
+- [x] No `TODO`, `FIXME` or stub for anything v0.1 promises.
+- [x] Run against **real, large** Rails applications. Six were checked: lobsters,
+      rubygems.org, Solidus, Mastodon, and two private production apps. None
+      crashed; none reported an analysis error. `script/ground_truth.rb` found
+      **zero false positives across 18 heavily-referenced symbols**.
+
+Still to do on real CI hardware:
+
+- [ ] Confirm the same matrix is green on GitHub Actions (it has never run
+      there: the repository has no remote yet).
+- [ ] Check behaviour on Linux and Windows. Only macOS has been exercised, and
+      the case-insensitivity bug found during validation was platform-specific.
+
+## 3. Documentation
+
+- [ ] Every command in `README.md` and `docs/CLI.md` produces the output shown.
+- [ ] Limitations are stated plainly and prominently.
+- [ ] Comparisons to Packwerk, Enola and test-selection tools are accurate,
+      respectful, and make no unverified superiority claim.
+- [ ] `CHANGELOG.md` has a dated `0.1.0` entry.
+- [ ] The JSON contract is documented with its schema version.
+- [ ] Rubydex and Prism are credited, with their licenses acknowledged.
+- [ ] No private paths, usernames, internal hostnames or secrets anywhere in the
+      repository, including fixtures and spec output.
+
+## 4. Repository setup
+
+- [ ] `LICENSE.txt` (MIT) present.
+- [ ] `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md` present.
+- [ ] Issue templates and a PR template present.
+- [ ] Branch protection on `main`; required status checks.
+- [ ] **GitHub Actions permissions minimised**, `permissions: contents: read` at
+      the workflow level, raised only where a job needs more.
+- [ ] No secrets configured that are not yet needed. In particular,
+      `release.yml.example` stays disabled until publishing is decided.
+- [ ] Private vulnerability reporting **enabled**, and the placeholder URL in
+      `SECURITY.md` replaced with the real advisory link.
+- [ ] Repository description and topics set (`ruby`, `rails`, `static-analysis`,
+      `impact-analysis`, `developer-tools`).
+
+## 5. Release mechanics
+
+- [ ] RubyGems account has **MFA enabled** (the gemspec requires it).
+- [ ] Decided: manual push, or trusted publishing via OIDC. Prefer OIDC over a
+      long-lived API key.
+- [ ] A signed tag for the release.
+- [ ] Release notes drafted from the changelog.
+
+## 6. Claims to double-check
+
+RippleEffect's value is that people can trust what it says. The same standard
+applies to how it is described.
+
+- [ ] **No benchmark number is quoted anywhere unless it was measured**, with the
+      hardware and project size stated.
+- [ ] No claim that test selection is safe to use for skipping CI.
+- [ ] No probability or percentage anywhere in the risk output or the marketing.
+- [ ] The privacy claims: no network, no telemetry, no boot, no `eval`, are all
+      still literally true of the shipped code. Re-verify; do not assume.
+
+## 7. Announcement
+
+- [ ] README opening lines work as a standalone description.
+- [ ] A short terminal capture of `inspect` and `diff` on a real app.
+- [ ] A post that leads with the problem (Rails hides its dependencies) rather
+      than the feature list, and that is honest about the limitations.
+- [ ] Prepared answers for the obvious questions: how it differs from Packwerk and
+      Enola, whether it is safe to skip tests with it (no), and how it handles
+      dynamic dispatch (it does not, and says so).

data/docs/RELEASING.md

@@ -0,0 +1,94 @@
+# Releasing
+
+> **RippleEffect 0.1.0 has not been released.** Before the first public release,
+> work through [PUBLIC_LAUNCH_CHECKLIST.md](PUBLIC_LAUNCH_CHECKLIST.md), in
+> particular, the name must be verified as available on RubyGems.
+
+## Versioning
+
+SemVer. The public API and what falls outside it are defined at the top of
+[CHANGELOG.md](../CHANGELOG.md).
+
+Two version numbers move independently:
+
+- `RippleEffect::VERSION`, the gem.
+- `RippleEffect::SCHEMA_VERSION`, the JSON contract. A breaking change here
+  increments both it and the gem's major version.
+- `RippleEffect::CACHE_SCHEMA_VERSION`, the on-disk cache. Bumping it invalidates
+  every existing cache, which is the intended effect; it is not part of SemVer.
+
+## Before you release
+
+Everything below must pass on a clean checkout.
+
+```console
+$ bundle install
+$ bundle exec rake            # specs + RuboCop
+$ bundle exec rake smoke      # build, isolated install, installed CLI
+$ gem build ripple_effect.gemspec   # must emit zero warnings
+```
+
+Then check by hand:
+
+- [ ] CI is green on every supported Ruby.
+- [ ] `CHANGELOG.md` has a dated entry for this version, and `## [Unreleased]` is
+      empty.
+- [ ] `lib/ripple_effect/version.rb` is bumped.
+- [ ] Every command shown in `README.md` and `docs/CLI.md` actually produces the
+      output shown. Run them against `spec/fixtures/rails_app`.
+- [ ] Fixtures, docs and specs contain no private paths, usernames or secrets.
+- [ ] `SCHEMA_VERSION` was incremented if the JSON contract changed.
+- [ ] Any benchmark number quoted anywhere was actually measured.
+
+## The release
+
+```console
+$ git switch main && git pull
+$ $EDITOR lib/ripple_effect/version.rb     # bump
+$ $EDITOR CHANGELOG.md                     # date the entry, empty Unreleased
+$ bundle install                           # refresh Gemfile.lock
+$ bundle exec rake && bundle exec rake smoke
+
+$ git add -A
+$ git commit -m "Release v0.1.0"
+$ git tag -s v0.1.0 -m "RippleEffect v0.1.0"
+$ git push origin main --follow-tags
+```
+
+Then publish:
+
+```console
+$ gem build ripple_effect.gemspec
+$ gem push ripple_effect-0.1.0.gem
+```
+
+Finally, cut a GitHub release from the tag, pasting the changelog entry.
+
+## RubyGems account requirements
+
+- **MFA is required** to own or push this gem. The gemspec sets
+  `rubygems_mfa_required`, so RubyGems will reject a push from an account without
+  it.
+- Decide before the first release whether pushes are manual or via a trusted
+  publishing workflow. `.github/workflows/release.yml.example` sketches the
+  automated route and is **not enabled**, do not activate it, or add
+  a `RUBYGEMS_API_KEY` secret, until that decision is made. Trusted publishing
+  (OIDC) is preferred over a long-lived API key.
+
+## After releasing
+
+- [ ] `gem install ripple_effect` from a clean machine and run `ripple-effect
+      doctor` against a real Rails app.
+- [ ] Confirm the RubyGems page renders the README and links correctly.
+- [ ] Open `## [Unreleased]` in `CHANGELOG.md` again.
+
+## Yanking
+
+Yank only for a security problem or a broken package. A yank breaks
+anyone who pinned the version.
+
+```console
+$ gem yank ripple_effect -v 0.1.0
+```
+
+Prefer releasing a fixed patch version.

data/docs/TESTING.md

@@ -0,0 +1,179 @@
+# Testing
+
+```console
+$ bundle exec rake          # specs + RuboCop: the gate
+$ bundle exec rspec         # specs only
+$ bundle exec rake smoke    # build, isolated install, installed-CLI checks
+$ bundle exec rake benchmark
+```
+
+## Layout
+
+```
+spec/
+├── spec_helper.rb
+├── support/
+│   ├── project_helpers.rb    # throwaway projects, the shared fixture analyzer
+│   └── git_helpers.rb        # throwaway Git repositories
+├── unit/                     # one file per class or extractor
+├── integration/              # fixture app, diff engine, JSON contract, CLI, docs
+└── fixtures/
+    └── rails_app/            # a static, Rails-shaped application
+```
+
+### The fixture application
+
+`spec/fixtures/rails_app/` is a small but realistic Rails-shaped app. It **never
+boots**, it is analysis input.
+
+It contains every relationship the product claims to understand:
+
+```
+route POST /checkout      -> OrdersController#create
+OrdersController#create   -> CheckoutService#call
+CheckoutService#call      -> BillingService#charge
+CheckoutService#call      -> InvoiceJob.perform_later
+Order                     -> belongs_to :account
+Order                     -> after_commit :send_receipt, if: :receiptable?
+Order#send_receipt        -> OrderMailer.receipt(...).deliver_later
+Subscription#renew!       -> RenewSubscriptionJob.perform_later
+Order                     -> include Auditable
+User                      -> delegate :display_name, to: :account
+```
+
+> **Its `*_spec.rb` files are fixtures, not tests.** They exist so the
+> test-relevance extractor has something to index. Both `.rspec` and the Rake task
+> exclude them; do not remove those exclusions.
+
+Indexing the fixture is the expensive part of the suite, so it is built once per
+run and shared via `ProjectHelpers.fixture_analyzer`.
+
+## Writing specs
+
+### Against throwaway files
+
+```ruby
+graph_for(
+  "app/models/order.rb" => "class Order\n  belongs_to :account\nend\n",
+  "app/models/account.rb" => "class Account\nend\n"
+) do |graph|
+  expect(edges_between(graph, "Order", "Account").map(&:type)).to include(:association)
+end
+```
+
+`with_project`, `with_analyzer` and `graph_for` all accept either a braced hash or
+brace-less `"path" => "source"` pairs, and clean up after themselves.
+
+### Against a real Git repository
+
+Diff specs use real, temporary repositories rather than stubs: a stub would let
+us pass against a Git that behaves differently from the user's.
+
+```ruby
+with_git_project("app/a.rb" => "class A\n  def call; end\nend\n") do |root|
+  write_files(root, "app/a.rb" => "class A\n  def call\n    1\n  end\nend\n")
+
+  expect(analyzer_for(root).diff(base: "main").changed_nodes.map(&:name)).to eq(["A#call"])
+end
+```
+
+Helpers: `write_files`, `delete_file`, `git`, `analyzer_for`.
+
+### Against the CLI
+
+Two layers, on purpose:
+
+- `spec/unit/cli_application_spec.rb` drives `Application#run` in-process with
+  `StringIO`. Fast, and coverage can see it.
+- `spec/integration/cli_spec.rb` runs the **real executable** in a subprocess, so
+  argument parsing, exit codes and the stdout/stderr split are checked as a user
+  experiences them.
+
+## What must stay covered
+
+The plan's bar, and the reason for each:
+
+- **Determinism**, identical input, byte-identical output. Without it the JSON
+  contract cannot be snapshot-tested.
+- **The JSON contract**, key order, schema version, no symbols, relative paths.
+- **Every CLI command**, including exit codes and which stream output goes to.
+- **Every extractor**, positive, negative, unresolvable, and config-off cases.
+- **Diff mapping**, modified, added, deleted, class-body, renamed, staged,
+  unstaged, untracked, invalid ref, and a path containing spaces.
+- **Safety**, that a malicious Git ref cannot reach a shell, that a symlink
+  pointing outside the root is refused, that YAML cannot construct objects, and
+  that indexing never executes the source.
+- **Documentation consistency**, `spec/integration/documentation_spec.rb` asserts
+  that every edge type, node kind and diagnostic code is documented, that the
+  config example matches the built-in defaults, and that the README lists every
+  command.
+
+## Coverage
+
+SimpleCov, with branch coverage, reporting to `coverage/`.
+
+The release expectation is **≥ 90% line coverage** of our own code. Current:
+**96%+ line**, **79%+ branch**, across 380+ examples.
+
+Coverage is a floor, not a goal: a covered line that asserts nothing is worth
+nothing.
+
+## The smoke test
+
+`bundle exec rake smoke` catches what specs structurally cannot:
+
+1. `gem build`, must produce zero warnings.
+2. Install into a throwaway `GEM_HOME`, with every Bundler variable stripped, so
+   the *installed* gem is what runs.
+3. `require "ripple_effect"` and check the version.
+4. Run the installed `ripple-effect` binary: `--help`, `version`, `doctor`,
+   `inspect`, `graph`.
+5. Check the installed CLI's JSON output parses and carries a schema version.
+
+This is how you find a file missing from the gemspec's file list, or a require
+that only resolves from the source tree. **It must pass before any release.**
+
+## Ground truth against real applications
+
+Fixtures prove the code does what it was written to do. They cannot tell you
+whether the answers are *true* of a real codebase.
+
+```console
+$ ruby script/ground_truth.rb ~/code/some-rails-app ~/code/another
+```
+
+For each application it picks the most-referenced uniquely-named methods and
+compares RippleEffect's reported dependents against every file that textually
+mentions that method name.
+
+The text search is a crude oracle on purpose. It effectively has no false
+negatives: if a file uses the method, the name appears in it: so **anything
+RippleEffect reports that grep did not find is a genuine false positive**, which
+is the failure mode this project cares about most. The script exits non-zero if
+it finds any.
+
+It is not symmetric: grep also matches comments, same-named methods on unrelated
+objects, and strings, so `unmatched` is a ceiling on what was missed rather than
+a defect count. Conventional test files are counted separately, since a spec is
+relevant because of where it lives, not because it names the method.
+
+v0.1 was checked this way against six applications: lobsters, rubygems.org,
+Solidus, Mastodon and two private production apps: covering Rails 7.0 to 8.1,
+classic ERB, API-only, Haml, and an engine monorepo. **18 symbols, zero false
+positives.**
+
+## CI
+
+`.github/workflows/ci.yml` runs:
+
+- **test**, Ruby 3.2, 3.3 and 3.4
+- **rails-matrix**, representative Ruby/Rails pairs (7.0, 7.1, 7.2, 8.0, 8.1)
+  via per-version Gemfiles. This job installs the real Rails version and runs
+  `spec/integration/rails_dsl_compatibility_spec.rb`, which pins the DSL forms
+  each version uses: otherwise the matrix would prove nothing, since the rest
+  of the suite never loads Rails.
+- **lint**, RuboCop on the current Ruby
+- **package**, `gem build` plus the installed-gem smoke test
+
+Benchmarks run locally, never as CI assertions: wall-clock numbers on shared CI
+runners are noise, and a flaky performance test trains people to ignore failures.

data/exe/ripple-effect

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ripple_effect"
+require "ripple_effect/cli/application"
+
+exit RippleEffect::CLI::Application.new.run(ARGV)