ripple_effect 0.1.0

data/README.md

@@ -0,0 +1,305 @@
+# RippleEffect
+
+> Change-impact analysis for Ruby on Rails.
+
+**RippleEffect maps the blast radius of Ruby on Rails changes.** It combines
+Ruby-aware static indexing with Rails semantics: callbacks, associations, routes,
+jobs, mailers, concerns, and test references: to explain what may be affected
+before you refactor.
+
+RippleEffect is deterministic and local. It does not boot your Rails application,
+connect to your database, call an LLM, or upload your source code.
+
+```console
+$ ripple-effect inspect 'BillingService#charge'
+
+BillingService#charge
+  app/services/billing_service.rb:2
+
+Direct dependents
+  app/jobs/invoice_job.rb:2                  InvoiceJob#perform
+    because: calls method (inference.unique_method_name) at app/jobs/invoice_job.rb:3
+    confidence: medium, depth: 1
+  app/services/checkout_service.rb:2         CheckoutService#call
+    because: calls method (inference.unique_method_name) at app/services/checkout_service.rb:3
+    confidence: medium, depth: 1
+
+Rails semantic dependents
+  app/jobs/invoice_job.rb:1                  InvoiceJob (job)
+    because: enqueues job (rails.job_perform) at app/jobs/invoice_job.rb:1
+    confidence: medium, depth: 2
+  config/routes.rb:5                         POST /checkout
+    because: route dispatches to (rails.route_to_controller) at config/routes.rb:5
+    confidence: medium, depth: 3
+
+Likely affected tests
+  spec/services/billing_service_spec.rb          reference (medium)
+  spec/services/checkout_service_spec.rb         reference (medium)
+  spec/jobs/invoice_job_spec.rb                  convention (medium)
+
+Blast radius
+  direct nodes: 4
+  transitive nodes: 10
+  max depth: 3
+  risk: high
+  because:
+    4 direct dependents
+    10 transitive dependents
+    reachable from 2 routes
+    reachable from 1 background job
+    impact spans 3 architectural layers (controllers, jobs, services)
+```
+
+## Why this exists
+
+Rails hides its most important dependencies. Nothing in your source calls
+`send_receipt`, an `after_commit` does. Nothing calls `InvoiceJob#perform`, a
+`perform_later` two files away does. Nothing calls `OrdersController#create`, a
+line in `config/routes.rb` does.
+
+Grep cannot see any of that. RippleEffect can, and it shows you the evidence so
+you can check its reasoning instead of trusting it.
+
+## How it differs from tools you may already use
+
+RippleEffect does not try to replace these:
+
+- **Packwerk** enforces package boundaries. Its static analysis focuses on
+  constant references and intentionally ignores method calls. RippleEffect is not
+  a boundary enforcer; it answers "what could this change break?" at method level.
+- **Enola** provides broad multi-language architecture intelligence. RippleEffect
+  is a Ruby gem and library first, focused narrowly on Rails source-symbol blast
+  radius with an embeddable API.
+- **Regression-test-selection tools** (Crystalball, gitlab-crystalball, Kaisoku)
+  optimise which tests run, often using runtime traces. For RippleEffect, test
+  relevance is supporting evidence, not the product: the explainable graph is.
+
+## Installation
+
+```console
+$ gem install ripple_effect
+```
+
+Or in a Gemfile:
+
+```ruby
+group :development do
+  gem "ripple_effect", require: false
+end
+```
+
+RippleEffect does not depend on Rails and never loads your application.
+
+## Quick start
+
+```console
+$ cd your-rails-app
+$ ripple-effect doctor                        # check what RippleEffect can see
+$ ripple-effect inspect 'BillingService#charge'
+$ ripple-effect diff main                     # blast radius of your branch
+$ bundle exec rspec $(ripple-effect tests main)
+```
+
+## Commands
+
+| Command | What it answers |
+| --- | --- |
+| `ripple-effect inspect SYMBOL` | What may be affected by changing this symbol, and why |
+| `ripple-effect diff BASE [HEAD]` | What may be affected by everything changed between two revisions |
+| `ripple-effect tests BASE [HEAD]` | Which test files are most likely relevant |
+| `ripple-effect graph SYMBOL` | The impacted subgraph, as DOT or JSON |
+| `ripple-effect doctor` | Whether this project can be analysed, and what was found |
+| `ripple-effect version` | The version |
+
+Symbols may be written as `User`, `User#activate!`, `User.find`, `User::Profile`,
+`OrdersController#create`, or `app/models/user.rb`.
+
+Full details, flags and exit codes: [docs/CLI.md](docs/CLI.md).
+
+### Machine-readable output
+
+Every command accepts `--format json` and emits a versioned, deterministic
+document: see [docs/CLI.md](docs/CLI.md#json-output) for the contract.
+
+```console
+$ ripple-effect diff main --format json | jq '.risk'
+{
+  "level": "high",
+  "score": 15.0,
+  "reasons": [
+    "4 direct dependents",
+    "10 transitive dependents",
+    "reachable from 2 routes",
+    "reachable from 1 background job"
+  ]
+}
+```
+
+### In CI
+
+```console
+$ ripple-effect diff origin/main --fail-on-risk critical
+```
+
+`diff` exits non-zero **only** when a `--fail-on-risk` threshold you asked for is
+met. Finding impact is not, by itself, a failure.
+
+## Library API
+
+The CLI is not the only product.
+
+```ruby
+require "ripple_effect"
+
+result = RippleEffect.analyze("BillingService#charge")
+
+result.impacted_nodes.map(&:name)   # => ["CheckoutService#call", ...]
+result.test_files                   # => ["spec/services/billing_service_spec.rb", ...]
+result.risk.level                   # => :high
+result.risk.reasons                 # => ["2 direct dependents", ...]
+result.to_h                         # => the JSON contract, as a Hash
+
+RippleEffect.diff("main")
+RippleEffect.tests_for("User#activate!")
+```
+
+For more control:
+
+```ruby
+project  = RippleEffect::Project.new(root: Dir.pwd)
+analyzer = RippleEffect::Analyzer.new(project: project)
+
+result = analyzer.inspect_symbol("BillingService#charge", depth: 2, min_confidence: :high)
+result.impacts.each do |impact|
+  puts "#{impact.node.name} (#{impact.confidence}) via #{impact.reason.description}"
+end
+```
+
+## Evidence and confidence
+
+Every edge in the graph carries an evidence code and a confidence band. Nothing is
+asserted without a reason you can go and look at.
+
+| Band | Meaning | Example |
+| --- | --- | --- |
+| `high` | An explicit static reference, or a literal Rails DSL relationship | `rails.after_commit`, `rubydex.constant_reference` |
+| `medium` | A target inferred from a strong convention | `inference.unique_method_name`, `rails.delegate` |
+| `low` | A naming or path heuristic only | `convention.request_spec_path` |
+
+By default RippleEffect traverses `high` and `medium` edges. Pass
+`--include-low-confidence` to widen, or `--min-confidence high` to narrow.
+
+A path is only as confident as its weakest link, and RippleEffect reports the
+*shortest* chain of reasoning, because that is the one you can check fastest.
+
+There are no percentages. Ruby is too dynamic for a number like "91% chance of
+breakage" to mean anything, and a made-up number is worse than no number.
+
+See [docs/ANALYSIS_MODEL.md](docs/ANALYSIS_MODEL.md) for every edge type and the
+exact resolution rules.
+
+## Safety and privacy
+
+RippleEffect reads files. That is all.
+
+- No network access, ever. No telemetry.
+- Your application is never booted and your source is never `eval`ed.
+- No database connection.
+- Git is invoked with argument arrays, never a shell string.
+- YAML config is loaded with safe loading: no aliases, no object deserialisation.
+- The cache is JSON, never Marshal.
+- Paths are normalised and confined to the project root; a symlink pointing
+  outside it is refused.
+
+`ripple-effect doctor` restates these guarantees. See [SECURITY.md](SECURITY.md).
+
+## Supported versions
+
+- Ruby 3.2, 3.3, 3.4: the full suite is run against each
+- Rails 7.0 – 8.1 (analysed statically; Rails is not a dependency)
+
+### Validated against real applications
+
+v0.1 was checked against six real Rails codebases: two private production
+applications and four large open-source ones: covering Rails 7.0 through 8.1,
+classic ERB apps, an API-only app, a Haml-based app, and an engine monorepo:
+
+| Application | Ruby files | Templates | Graph | Cold |
+| --- | --- | --- | --- | --- |
+| lobsters | 258 | 121 erb | 1.4k nodes / 4.8k edges | 0.5s |
+| rubygems.org | 1,044 | 173 erb | 5.7k nodes / 20.6k edges | 2.2s |
+| Solidus (6 engines) | 1,810 | 299 erb | 8.9k nodes / 22.8k edges | 6.6s |
+| Mastodon | 2,574 | 46 erb | 13.3k nodes / 47.7k edges | 4.4s |
+| private app (Rails 7.0) | 521 | 688 erb | 5.0k nodes / 12.8k edges | 0.8s |
+| private app (Rails 8.0) | 845 | 33 erb | 7.7k nodes / 21.1k edges | 1.2s |
+
+None crashed, and none reported an analysis error. Warm runs are well under a
+tenth of a second.
+
+Dependents were ground-truthed against an exhaustive text search of each codebase
+(`script/ground_truth.rb`). Across **18 heavily-referenced methods in those six
+applications, there were zero false positives**, RippleEffect never claimed a
+dependency that was not really there. Several were exact matches (151 of 151
+files for one Mastodon method, 47 of 47 for one private-app helper).
+
+Recall is the weaker side, by design: where a receiver is ambiguous RippleEffect
+records a diagnostic instead of guessing, so it misses some real relationships.
+See [Known limitations](#known-limitations).
+
+That is a spot check, not a guarantee. Please report anything it gets wrong.
+
+## Known limitations
+
+RippleEffect prefers a false negative to a confident false positive. It will tell
+you when it does not know.
+
+- **Dynamic dispatch.** `send`, `public_send`, `method_missing` and metaprogrammed
+  methods are not resolved. Where a receiver cannot be resolved and one method
+  name matches uniquely, a `medium`-confidence edge is created; where several
+  match, a diagnostic is recorded and no edge is invented.
+- **Polymorphic associations** have no static target. They are reported as a
+  diagnostic, not resolved.
+- **Non-literal Rails DSL.** Callbacks, associations and routes built from
+  variables, constants or loops are not read.
+- **Route DSL coverage** is conservative: explicit verbs with `to:`,
+  `root`, `resources`/`resource` with `only:`/`except:`/`controller:`, `namespace`
+  and `scope`. Constraints, `concern`, and `direct` are not modelled.
+- **Test selection is a recommendation.** It is never permission to skip the rest
+  of your suite. When a global or boot-impact file changes, `tests` refuses to
+  print a narrowed list unless you pass `--allow-unsafe-focus`.
+- **Recall is incomplete.** Where a call's receiver is ambiguous,
+  RippleEffect records a diagnostic and adds no edge, so some real dependencies
+  are missed. Run with `--verbose` to see exactly what was skipped.
+- **ERB templates are indexed**, but a call with an explicit receiver inside one
+  (`<%= @order.total %>`) is not resolved: the receiver's type is unknown.
+  Non-ERB templates (Haml, Slim, Builder), JavaScript, and SQL are not indexed.
+
+## Development
+
+```console
+$ bin/setup                    # or: bundle install
+$ bundle exec rake             # specs + RuboCop
+$ bundle exec rspec
+$ bundle exec rubocop
+$ bundle exec rake smoke       # build, install into a temp GEM_HOME, run the CLI
+$ bundle exec rake benchmark
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [ARCHITECTURE.md](ARCHITECTURE.md) and
+[docs/TESTING.md](docs/TESTING.md).
+
+## Status
+
+v0.1.0 is an early release. The analysis model and CLI are stable enough to use,
+but expect rough edges on unusual codebases. Bug reports with a small
+reproduction are very welcome.
+
+## Acknowledgements
+
+RippleEffect's Ruby declaration and reference index is powered by
+[Rubydex](https://github.com/Shopify/rubydex) (MIT), and its Rails DSL parsing by
+[Prism](https://github.com/ruby/prism).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,73 @@
+# Security policy
+
+## Threat model
+
+RippleEffect reads files in your project and runs `git`. That is the whole of it.
+
+It is designed to be safe to run against a codebase you do not fully trust, and to
+be safe to run in CI.
+
+### Guarantees
+
+| Guarantee | How |
+| --- | --- |
+| **No network access** | Nothing in the gem opens a socket. Analysis is entirely local. |
+| **No telemetry** | Nothing is collected, counted, or transmitted. |
+| **Your application is never booted** | RippleEffect analyses source statically. It never loads your Rails environment or initializers. |
+| **Your source is never evaluated** | No `eval`, `instance_eval`, or `Kernel#load` of analysed code. Parsing only. |
+| **No database connection** | No adapter, connection, or query, ever. |
+| **Safe subprocess invocation** | Git runs through `Open3.capture3` with argument arrays. A ref containing `; rm -rf /` is a ref that does not exist, not a command. There is a spec for this. |
+| **Safe YAML** | Config is read with `YAML.safe_load_file`, no aliases and no permitted classes. A config file cannot construct objects. |
+| **Safe cache** | The cache is JSON. Never Marshal, which would turn a corrupted cache file into arbitrary object construction. |
+| **Path confinement** | Paths are normalised and symlinks resolved before comparison; anything resolving outside the project root is refused. |
+
+`ripple-effect doctor` restates these at runtime.
+
+### What RippleEffect writes
+
+Only the cache, by default `tmp/ripple_effect/`, containing `manifest.json` and
+`graph.json`. Disable it with `cache.enabled: false` or `--no-cache`.
+
+The cache contains symbol names, file paths and line numbers from your project. It
+should be treated with the same care as your source, and should not be committed.
+
+### Residual risks
+
+- **Subprocess:** RippleEffect executes the `git` on your `PATH`. A compromised
+  `git` is outside its control.
+- **Dependencies:** `rubydex` (which includes a native extension) and `prism`.
+- **Output:** analysis output contains your symbol names and paths. Redact before
+  sharing a report publicly.
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| 0.1.x | Yes |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for a security problem.**
+
+Report it privately through GitHub's private vulnerability reporting:
+
+<https://github.com/iamzayn19/ripple-effect/security/advisories/new>
+
+If private reporting is not enabled yet, email <iamzayn19@gmail.com> instead.
+
+Please include:
+
+- what the vulnerability allows an attacker to do,
+- the affected version,
+- reproduction steps or a proof of concept,
+- any suggested fix.
+
+### What to expect
+
+- **Acknowledgement** within 3 working days.
+- **An initial assessment** within 10 working days.
+- **A fix or a plan** shared with you before public disclosure.
+- **Credit** in the release notes, unless you prefer otherwise.
+
+We ask that you give us a reasonable opportunity to fix an issue before disclosing
+it publicly.

data/docs/ANALYSIS_MODEL.md

@@ -0,0 +1,275 @@
+# Analysis model
+
+What RippleEffect claims, what it refuses to claim, and why.
+
+## Node kinds
+
+| Kind | What it represents |
+| --- | --- |
+| `file` | A source file |
+| `test_file` | A file under `spec/` or `test/` |
+| `class` | A class declaration |
+| `module` | A module declaration |
+| `instance_method` | `Order#total` |
+| `class_method` | `Order.recent` |
+| `route` | One routing entry, e.g. `POST /checkout` |
+| `callback` | One lifecycle callback declaration |
+| `association` | Reserved for association nodes; v0.1 models associations as edges |
+| `job` | An Active Job class, as a background entry point |
+| `mailer_action` | One mailer action, e.g. `OrderMailer.receipt` |
+| `view` | An ERB template or partial |
+| `unknown` | Fallback; not emitted in v0.1 |
+
+### Node IDs
+
+Deterministic and readable, never random. The path is part of the ID so a class
+reopened in two files does not collide.
+
+```
+file:app/models/user.rb
+class:app/models/order.rb:Order
+method:app/services/billing_service.rb:BillingService#charge
+route:config/routes.rb:5:route:POST:/checkout
+```
+
+### Canonical symbol names
+
+| Kind | Canonical form | Also accepted |
+| --- | --- | --- |
+| Instance method | `User#activate!` |, |
+| Singleton method | `User.find` | `User::find` |
+| Namespaced constant | `User::Profile` |, |
+
+## Edge direction
+
+One rule, never varied:
+
+> `from_id` **depends on / invokes / references** `into_id`
+
+Walking edges backwards from a changed node therefore finds its dependents.
+
+## Edge types
+
+| Type | Meaning | Typical evidence |
+| --- | --- | --- |
+| `constant_reference` | A constant is mentioned | `rubydex.constant_reference` |
+| `method_call` | A method is called | `rubydex.method_reference`, `inference.unique_method_name` |
+| `inheritance` | `class B < A` | `ruby.superclass` |
+| `include` | `include M` | `ruby.include` |
+| `prepend` | `prepend M` | `ruby.prepend` |
+| `extend` | `extend M` | `ruby.extend` |
+| `association` | An ActiveRecord association | `rails.belongs_to`, `rails.has_many`, … |
+| `callback` | A lifecycle callback, or its condition | `rails.after_commit`, `rails.callback_condition`, … |
+| `delegate` | `delegate ..., to:` | `rails.delegate` |
+| `route_handler` | A route dispatches to a controller action | `rails.route_to_controller` |
+| `job_enqueue` | A job is enqueued, or a job class owns its `#perform` | `rails.perform_later`, `rails.job_perform` |
+| `mailer_delivery` | Mail is delivered, or a mailer owns its action | `rails.deliver_later`, `rails.mailer_action` |
+| `test_convention` | A test covers code | `convention.rspec_path`, `convention.minitest_path`, `convention.request_spec_path` |
+| `file_reference` | Structural containment, and template rendering | `ruby.file_declares`, `ruby.defines_method`, `rails.renders_template`, `rails.render_partial` |
+
+### Structural edges
+
+`file_reference` edges are graph plumbing: a file "depends on" the classes it
+declares, and a class on the methods it defines. They exist so a file-level change
+can reach its code, and so a method change reaches everything that depends on its
+class.
+
+Text output hides them, because reporting a file as a dependent of its own method
+buries the real answer. JSON keeps them.
+
+## Confidence
+
+Three bands, no percentages. Ruby is too dynamic for a number like "91% chance of
+breakage" to mean anything, and a fabricated number is worse than none.
+
+| Band | Rule | Examples |
+| --- | --- | --- |
+| `high` | An explicit static reference, or a literal Rails DSL relationship | `rails.after_commit`, `rubydex.constant_reference`, `ruby.superclass` |
+| `medium` | A target inferred from a strong convention | `inference.unique_method_name`, `rails.delegate` |
+| `low` | A naming or path heuristic only | `convention.request_spec_path` |
+
+**A path is as confident as its weakest link.** Default traversal is `high` +
+`medium`; `low` requires `--include-low-confidence`.
+
+## Method call resolution
+
+| Case | Example | Result |
+| --- | --- | --- |
+| Receiver resolved by the index | `validate!` inside the same class | `high` edge |
+| Explicit constant receiver | `InvoiceJob.perform_later(id)` | `high` edge |
+| Unresolved receiver, one method in the project has that name | `billing.charge(order)` | `medium` edge |
+| Unresolved receiver, several methods share the name | `x.run` where `A#run` and `B#run` exist | **No edge**, `unresolved_method_receiver` diagnostic |
+| `send`, `public_send`, dynamic names | `public_send(name)` | **No edge** |
+| `method_missing`, generated methods |, | **No edge** |
+
+The fourth row is the heart of the design. Choosing between candidates would
+produce a confident falsehood, and one of those costs more trust than many honest
+"I don't know"s.
+
+## Rails semantics
+
+### Associations
+
+Literal macros only: `belongs_to`, `has_one`, `has_many`,
+`has_and_belongs_to_many`.
+
+- Target resolved from an explicit `class_name:` when literal, otherwise from
+  Rails' own naming convention (`has_many :orders` → `Order`).
+- Metadata records `macro`, `association_name`, `class_name`, `foreign_key`,
+  `through`.
+- Scopes and blocks are **never executed**.
+- **Polymorphic** targets have no static answer. They produce an
+  `unresolved_polymorphic_association` diagnostic, never an invented constant.
+- A target that is not indexed produces `unresolved_association_target`.
+
+### Callbacks
+
+`before_validation`, `after_validation`, `before/around/after` × `save`, `create`,
+`update`, `destroy`, plus `after_commit`, `after_rollback`, `after_touch`,
+`after_initialize`, `after_find`.
+
+Each declaration becomes a `callback` node, so the reason survives into the
+explanation. The model reaches the callback; the callback reaches the method.
+
+- Symbol and string names are both read, including several in one call.
+- `if:` / `unless:` predicates get their own edge: they run on every save too.
+- A block callback becomes an anonymous node anchored to its line range; the calls
+  inside it are indexed normally.
+
+### Jobs
+
+A class is a job when it inherits from `ApplicationJob` or `ActiveJob::Base`,
+directly or through intermediates.
+
+- `perform_later` and `perform_now` with a constant receiver link the caller to
+  `Job#perform` at `high` confidence.
+- `Job.set(...).perform_later` is followed, because the constant is still visible.
+- A non-constant receiver is ignored. No queue or adapter is ever loaded.
+
+### Mailers
+
+A class is a mailer when it inherits from `ApplicationMailer` or
+`ActionMailer::Base`. Each instance method becomes a `mailer_action` node —
+Action Mailer synthesises the class-level call, so it exists nowhere in the source.
+
+`OrderMailer.receipt(order).deliver_later` links the sender to
+`OrderMailer#receipt`.
+
+### Routes
+
+conservative. Supported:
+
+- Explicit verbs with `to: "controller#action"`, and `root to:`
+- `resources` / `resource`, honouring literal `only:`, `except:` and `controller:`
+- `namespace` (prefixes both path and controller module)
+- `scope` with a literal path or `module:`
+- Nested resources inside a `resources` block
+
+Not modelled in v0.1: constraints, `concern`, `direct`, `resolve`, and routes
+built from variables or loops. A route whose controller is not indexed produces
+`unresolved_route_controller`.
+
+### Views
+
+ERB templates are part of the graph. The Ruby is lifted out of the ERB tags and
+parsed with Prism; a template is never rendered and its code is never executed.
+
+Rails' own ERB handler: not stdlib `ERB`, is what understands
+`<%= form_with do |f| %>`, so the tag contents are read directly rather than
+compiled through `ERB#src`, which turns that form into a syntax error.
+
+| Relationship | Evidence | Confidence |
+| --- | --- | --- |
+| A controller action renders its conventional template | `rails.renders_template` | `high` |
+| A template renders a partial | `rails.render_partial` | `high` |
+| A template references a constant | `view.constant_reference` | `high` |
+| A template calls a uniquely-named helper or model method | `view.helper_call` | `medium` |
+| `helper_method :foo` exposes a controller method to templates | `rails.helper_method` | `high` on the controller, `medium` via an included concern |
+
+A call with an explicit receiver in a template (`@order.total`) is not resolved:
+the receiver is a local or instance variable whose type is unknown.
+
+### Delegation
+
+`delegate :name, to: :account` names a **receiver**, not a class. RippleEffect
+resolves it through an association of the same name on the same class, and
+otherwise through the conventional class name: at `medium` confidence, because
+it is an inference.
+
+An unresolvable receiver produces `unresolved_delegate_target` and no edge.
+
+## Test relevance
+
+Ranked by *why* a test was reached:
+
+| Rank | Reason | Meaning |
+| --- | --- | --- |
+| 1 | `reference` | The test actually references the changed code |
+| 2 | `rails_semantic` | Reached through a Rails relationship |
+| 3 | `convention` | It sits at the conventional path |
+| 4 | `heuristic` | A looser path match, such as a request spec |
+
+A changed test file always ranks first.
+
+**Test selection is a recommendation, never permission to skip the rest of your
+suite.** RippleEffect can prove a test is probably relevant; it cannot prove one is
+irrelevant.
+
+## Risk
+
+Discrete bands with stated reasons: a ranking aid for reviewers, not a defect
+prediction.
+
+| Points | For |
+| --- | --- |
+| +1 each (max 8) | Direct dependents |
+| +0.5 each (max 8) | Transitive dependents |
+| +2 | Reachable from a route |
+| +2 | Reachable from a background job |
+| +2 | Reachable from a model callback |
+| +1 | Reachable from a mailer |
+| +3 | The change touches a class or module body, not just method bodies |
+| +3 | A global or boot-impact file changed |
+| +2 | Impact spans 3 or more architectural layers |
+
+| Score | Band |
+| --- | --- |
+| `>= 18` | `critical` |
+| `>= 10` | `high` |
+| `>= 4` | `medium` |
+| `< 4` | `low` |
+
+File nodes are excluded from the dependent counts.
+
+## Diagnostics
+
+Non-fatal facts about the analysis. Match on `code`, not on message text: codes
+are stable, messages are not.
+
+| Code | Meaning |
+| --- | --- |
+| `unresolved_polymorphic_association` | A polymorphic `belongs_to` has no static target |
+| `unresolved_association_target` | The association's target class is not indexed |
+| `unresolved_delegate_target` | The delegation receiver could not be resolved |
+| `unresolved_method_receiver` | A call site's receiver is ambiguous or unknown |
+| `unresolved_route_controller` | A route points at a controller action that is not indexed |
+| `unparsed_file` | A file could not be read or parsed; analysis continued |
+| `index_note` | The indexer reported a lint finding about a file it parsed successfully |
+| `unmapped_changed_lines` | Changed lines could not be mapped to a declaration |
+| `global_file_changed` | A boot-impact file changed; impact may be broader than shown |
+| `deleted_file` | A file was deleted; anything referencing it may break |
+| `renamed_file` | A file was renamed |
+| `cache_discarded` | The cache was unreadable and has been rebuilt |
+| `dynamic_dispatch` | Reserved for dynamic dispatch reporting |
+| `empty_index` | Files were indexed but no declarations found; results are not trustworthy |
+
+Severities are `info`, `warning` and `error`. Text output shows warnings by
+default and everything with `--verbose`; JSON always includes all of them.
+
+## What RippleEffect does not do
+
+- Execute your code, boot Rails, or connect to a database.
+- Resolve dynamic dispatch or metaprogrammed methods.
+- Analyse non-ERB templates (Haml, Slim, Builder), JavaScript, or SQL.
+- Follow impact across repositories.
+- Prove that unselected tests are unnecessary.