ripple_effect 0.1.0

data/docs/CLI.md

@@ -0,0 +1,276 @@
+# CLI reference
+
+```
+ripple-effect COMMAND [options]
+```
+
+## Exit codes
+
+These are part of the interface and are the same for every command.
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | A threshold you asked us to enforce was met (`--fail-on-risk`) |
+| `2` | Your input: a bad query, bad configuration, bad usage, or a refused unsafe focus |
+| `3` | Our problem: the analyzer or index failed |
+
+Finding impact is never, by itself, a failure.
+
+## Global options
+
+Accepted **before or after** the subcommand.
+
+| Option | Meaning |
+| --- | --- |
+| `--root PATH` | Project root (default: current directory) |
+| `--config PATH` | Path to a `.ripple-effect.yml`; must exist |
+| `--format text\|json` | Output format (default `text`; `tests` defaults to `paths`) |
+| `--no-cache` | Ignore and do not write the graph cache |
+| `--verbose` | Include stats and every diagnostic |
+| `--quiet` | Suppress non-essential output |
+| `-v`, `--version` | Print the version |
+| `-h`, `--help` | Show usage |
+
+## `inspect`
+
+```
+ripple-effect inspect SYMBOL [options]
+```
+
+What may be affected by changing `SYMBOL`, and why.
+
+**Symbol forms**
+
+| Form | Example |
+| --- | --- |
+| Class or module | `User`, `User::Profile` |
+| Instance method | `User#activate!` |
+| Singleton method | `User.find` (`User::find` is also accepted) |
+| File | `app/models/user.rb` |
+
+| Option | Meaning |
+| --- | --- |
+| `--depth N\|all` | Maximum hops to follow (default: unlimited) |
+| `--path PATH` | Disambiguate a symbol declared in several files |
+| `--min-confidence high\|medium\|low` | Only follow edges at least this confident |
+| `--include-low-confidence` | Also follow low-confidence edges |
+| `--direction dependents\|dependencies\|both` | Default `dependents` |
+
+```console
+$ ripple-effect inspect 'BillingService#charge'
+$ ripple-effect inspect User.find --depth 2 --format json
+$ ripple-effect inspect 'User#save' --path lib/legacy/user.rb
+```
+
+An ambiguous symbol is an error, never a guess:
+
+```console
+$ ripple-effect inspect 'User#save'
+Error: `User#save` matched 2 declarations
+  1. app/models/user.rb:42
+  2. lib/legacy/user.rb:18
+Use --path to disambiguate.
+```
+
+## `diff`
+
+```
+ripple-effect diff BASE [HEAD] [options]
+```
+
+The blast radius of everything changed between two revisions.
+
+**Revision semantics**
+
+| Invocation | Compares |
+| --- | --- |
+| `diff main` | `main` against the **working tree**, committed, staged, unstaged and untracked |
+| `diff main HEAD` | `main` against `HEAD`, committed changes only |
+| `diff v1.2.0 HEAD` | Any two refs |
+
+| Option | Meaning |
+| --- | --- |
+| `--depth N\|all` | Maximum hops to follow |
+| `--min-confidence LEVEL` | Only follow edges at least this confident |
+| `--include-low-confidence` | Also follow low-confidence edges |
+| `--fail-on-risk low\|medium\|high\|critical` | Exit `1` when risk reaches this level |
+
+```console
+$ ripple-effect diff main
+$ ripple-effect diff origin/main --fail-on-risk critical
+```
+
+## `tests`
+
+```
+ripple-effect tests BASE [HEAD] [options]
+```
+
+The test files most likely relevant to a change.
+
+The default `paths` format prints **only** test paths on stdout: every warning
+goes to stderr: so it composes:
+
+```console
+$ bundle exec rspec $(ripple-effect tests main)
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--runner rspec\|minitest\|auto` | Test framework (default `auto`) |
+| `--allow-unsafe-focus` | Print a narrowed list even when a global file changed |
+| `--min-confidence LEVEL` | Only follow edges at least this confident |
+| `--format paths\|text\|json` | Default `paths` |
+
+### The unsafe-focus refusal
+
+When a boot-impact file changes. `Gemfile`, `config/initializers/**`,
+`config/routes.rb`, `spec/rails_helper.rb`, and the rest of
+`tests.unsafe_global_files`, the graph cannot bound what it reaches. Printing a
+short list would be an implicit claim that the other tests are unnecessary, which
+RippleEffect does not make.
+
+So the command prints nothing to stdout and exits `2`:
+
+```console
+$ ripple-effect tests main
+WARNING: focused tests may be incomplete because config/initializers/payments.rb changed.
+These files affect application boot or configuration, so the impact graph cannot bound what they reach.
+Run your full suite, or pass --allow-unsafe-focus to print a narrowed list anyway.
+```
+
+## `graph`
+
+```
+ripple-effect graph SYMBOL [options]
+```
+
+The impacted subgraph: not the whole project.
+
+| Option | Meaning |
+| --- | --- |
+| `--format dot\|json` | Default `dot` |
+| `--depth N\|all` | Maximum hops to follow |
+| `--path PATH` | Disambiguate a symbol declared in several files |
+
+```console
+$ ripple-effect graph 'BillingService#charge' --format dot | dot -Tsvg -o impact.svg
+```
+
+Node shapes distinguish routes, jobs, callbacks and mailers; edge line styles show
+confidence (solid = high, dashed = medium, dotted = low).
+
+## `doctor`
+
+```
+ripple-effect doctor
+```
+
+Checks the project root, Git availability, Ruby version support, Rails-like
+layout, the static index backend, config validity, how many files were indexed,
+diagnostic count, and cache writability: then restates the privacy guarantees.
+
+Exits `2` if the Ruby version is unsupported. Makes no network calls.
+
+## `version`
+
+```
+ripple-effect version
+```
+
+Prints the bare semantic version, so it can be captured directly:
+
+```console
+$ VERSION=$(ripple-effect version)
+```
+
+`--verbose` adds the schema version, Ruby version and index backend; `--format
+json` emits the same as JSON.
+
+## JSON output
+
+Every command accepts `--format json`. The document is versioned and
+deterministic: identical input produces byte-identical output.
+
+```json
+{
+  "schema_version": 1,
+  "tool": { "name": "ripple_effect", "version": "0.1.0" },
+  "query": { "type": "symbol", "value": "BillingService#charge" },
+  "changed_nodes": [],
+  "impacted_nodes": [
+    {
+      "id": "method:app/services/checkout_service.rb:CheckoutService#call",
+      "kind": "instance_method",
+      "name": "CheckoutService#call",
+      "qualified_name": "CheckoutService#call",
+      "path": "app/services/checkout_service.rb",
+      "start_line": 2,
+      "end_line": 5,
+      "metadata": {},
+      "depth": 1,
+      "confidence": "medium",
+      "source_id": "method:app/services/billing_service.rb:BillingService#charge",
+      "evidence_path": [
+        {
+          "type": "method_call",
+          "evidence": "inference.unique_method_name",
+          "confidence": "medium",
+          "location": "app/services/checkout_service.rb:3"
+        }
+      ]
+    }
+  ],
+  "tests": [
+    {
+      "path": "spec/services/billing_service_spec.rb",
+      "reason": "reference",
+      "evidence": "inference.unique_method_name",
+      "confidence": "medium",
+      "depth": 1
+    }
+  ],
+  "risk": { "level": "high", "score": 15.0, "reasons": ["4 direct dependents"] },
+  "diagnostics": [
+    {
+      "severity": "info",
+      "code": "unresolved_route_controller",
+      "path": "config/routes.rb",
+      "line": 4,
+      "message": "GET /health routes to HealthController#show, which is not indexed"
+    }
+  ],
+  "stats": { "files_indexed": 23, "nodes": 75, "edges": 160, "cache": "hit" }
+}
+```
+
+Guarantees:
+
+- `schema_version` is always present and increments on any breaking change.
+- All file paths are project-relative. (Route URLs also begin with `/`, those are
+  URLs, in `metadata`, not paths.)
+- No Ruby symbols; every value is JSON-native.
+- Key order is fixed.
+
+Unlike text output, JSON includes structural nodes (files, and the class that owns
+a changed method). Text hides them as noise; machine consumers may want them.
+
+### Errors in JSON mode
+
+Errors are JSON too, on **stderr**, with a non-zero exit. stdout stays empty.
+
+```json
+{
+  "schema_version": 1,
+  "tool": { "name": "ripple_effect", "version": "0.1.0" },
+  "error": {
+    "code": "query_error",
+    "type": "RippleEffect::QueryError",
+    "message": "no indexed symbol matches `Nope#nope`"
+  }
+}
+```
+
+Error codes: `usage`, `query_error`, `configuration_error`, `project_error`,
+`git_error`, `index_error`, `unsafe_focus`.

data/docs/CONFIGURATION.md

@@ -0,0 +1,178 @@
+# Configuration
+
+RippleEffect works with no configuration. To override anything, add
+`.ripple-effect.yml` to your project root.
+
+The `version` key is **required** whenever the file exists, so that a future schema
+change can be detected rather than silently misread.
+
+## Full schema
+
+Every value shown is the default.
+
+```yaml
+version: 1
+
+paths:
+  include:
+    - app/**/*.rb
+    - lib/**/*.rb
+    - config/routes.rb
+    - config/routes/**/*.rb
+    - spec/**/*.rb
+    - test/**/*.rb
+  views:
+    - app/views/**/*.erb
+  discover_engines: true
+  exclude:
+    - vendor/**
+    - node_modules/**
+    - tmp/**
+    - log/**
+    - coverage/**
+    - public/assets/**
+    - storage/**
+    - .bundle/**
+    - .git/**
+
+analysis:
+  min_confidence: medium
+  default_depth: all
+  include_low_confidence: false
+
+rails:
+  routes: true
+  associations: true
+  callbacks: true
+  jobs: true
+  mailers: true
+  delegation: true
+  views: true
+
+tests:
+  framework: auto
+  unsafe_global_files:
+    - Gemfile
+    - Gemfile.lock
+    - config/application.rb
+    - config/environment.rb
+    - config/boot.rb
+    - config/environments/**
+    - config/initializers/**
+    - config/routes.rb
+    - spec/spec_helper.rb
+    - spec/rails_helper.rb
+    - test/test_helper.rb
+
+cache:
+  enabled: true
+  directory: tmp/ripple_effect
+```
+
+## Keys
+
+### `paths`
+
+Which files are indexed. Globs are project-relative; a leading `./` is stripped.
+
+Test directories are included deliberately: indexing your specs is what lets
+RippleEffect rank a test that *references* the changed code above one that merely
+sits at the conventional path.
+
+### `paths.views`
+
+ERB templates. These are not Ruby files, so they need their own patterns.
+
+In a classic server-rendered Rails application the view layer is a large part of
+the real dependency graph: helpers and models are used almost entirely from
+templates. Omitting views does not just lose detail, it systematically
+*understates* every helper's blast radius while the answer still looks complete.
+
+Set to `[]` to skip templates entirely (or use `rails.views: false`).
+
+### `paths.discover_engines`
+
+Default `true`. Also index directories that are Rails engines or gems in their
+own right: a directory with both an `app/` and either a `*.gemspec` or a
+`lib/**/engine.rb`.
+
+Engine monorepos are common: Solidus and Spree are built this way, and plenty of
+applications keep an `engines/` directory. Such repos often have no top-level
+`app/` at all, so without this the default patterns would match almost nothing.
+The gemspec-or-engine requirement is what keeps ordinary subdirectories out.
+
+`ripple-effect doctor` lists the engines it found.
+
+### `analysis.min_confidence`
+
+`high`, `medium` (default) or `low`. Edges weaker than this are not traversed.
+
+- `high`, only explicit static references and literal Rails DSL relationships.
+- `medium`, also convention-inferred targets. The default.
+- `low`, also naming and path heuristics. Noisy.
+
+### `analysis.default_depth`
+
+A positive integer, or `all` (default) for unlimited, cycle-protected traversal.
+`--depth` overrides it per invocation.
+
+### `analysis.include_low_confidence`
+
+Lowers the floor to `low`. Equivalent to always passing
+`--include-low-confidence`.
+
+### `rails.*`
+
+Switches individual Rails extractors off. Useful when a DSL in your codebase is
+producing noise, or to speed up analysis of a non-Rails project.
+
+The Ruby structure extractor cannot be disabled: every other extractor builds on
+the nodes it creates.
+
+### `tests.framework`
+
+`auto` (default), `rspec` or `minitest`. `auto` looks for `spec/`, then `test/`.
+
+### `tests.unsafe_global_files`
+
+Files whose change can affect almost anything. When one of these changes, `diff`
+records a `global_file_changed` diagnostic, risk scoring adds points, and `tests`
+refuses to print a narrowed list without `--allow-unsafe-focus`.
+
+Add anything in your project with the same property: a central initializer, a
+generated schema, a shared factory file.
+
+### `cache`
+
+`enabled` (default `true`) and `directory` (default `tmp/ripple_effect`).
+
+The cache is invalidated by content, so you rarely need to clear it by hand.
+`--no-cache` skips it for one run.
+
+## Validation
+
+RippleEffect distinguishes two kinds of mistake:
+
+- **An unknown top-level key is a warning**, surfaced by `doctor`. A typo in a key
+  name is usually harmless.
+- **An invalid value for a known key is a hard error.** A bad value would silently
+  change what gets analysed, and a silently wrong answer is worse than no answer.
+
+```console
+$ ripple-effect doctor
+Configuration warnings
+  unknown configuration key(s): analisys
+
+$ ripple-effect inspect User
+Error: `min_confidence` must be one of high, medium, low, got "certain"
+```
+
+## Safety
+
+The file is read with `YAML.safe_load_file`: no aliases, no permitted classes, no
+object deserialisation. A config file cannot execute anything.
+
+## Example
+
+Copy [`.ripple-effect.yml.example`](../.ripple-effect.yml.example) to
+`.ripple-effect.yml` and edit.

data/docs/DECISIONS.md

@@ -0,0 +1,210 @@
+# Architecture decisions
+
+A record of the choices that shaped RippleEffect, and what they cost.
+
+---
+
+## 1. Rubydex for Ruby indexing, behind an adapter
+
+**Decision.** Use [Rubydex](https://github.com/Shopify/rubydex) for Ruby
+declarations and references, and seal it behind `StaticIndex::Adapter`.
+
+**Why.** Writing a correct Ruby indexer: constant resolution, lexical scope,
+singleton classes, mixin ancestry: is a multi-year project and not what makes
+RippleEffect valuable. Rubydex does it well and is MIT-licensed.
+
+But Rubydex is young; version 0.4.1 is what this was built against, and its API is
+still moving. Depending on it directly throughout the codebase would make every
+future Rubydex release a potential rewrite.
+
+**Cost.** A translation layer, and normalisation work at the boundary: Rubydex
+reports zero-indexed lines and names singleton methods `Order::<Order>#recent`.
+The adapter converts both. A spec asserts no Rubydex object escapes.
+
+**Result.** Replacing the indexer means rewriting one file.
+
+---
+
+## 2. Prism for the Rails DSL, in addition to the index
+
+**Decision.** Parse Rails DSL calls with Prism rather than extending the index.
+
+**Why.** A declaration index answers "what is defined and what is referenced". It
+tells us *that* `belongs_to` was called; it does not tell us it was called with
+`:account, class_name: "User"`. Rails semantics live entirely in those arguments.
+
+**Cost.** A second dependency, and a second pass over the source. Mitigated by a
+shared `SourceCache`, so each file is parsed at most once regardless of how many
+extractors need it.
+
+**Note.** Prism is a default gem from Ruby 3.3, but not on 3.2, so it is an
+explicit runtime dependency.
+
+---
+
+## 3. Confidence bands, never percentages
+
+**Decision.** Three bands. `high`, `medium`, `low`. No numeric probability in any
+human-facing output.
+
+**Why.** A number like "91% likely to break" implies a calibrated model. There is
+no such model, and there could not be one without a large corpus of real changes
+and their outcomes. A fabricated number is worse than no number, because people
+act on it.
+
+**Cost.** Less impressive output. Coarser ranking.
+
+**Consequence.** A numeric weight exists internally for traversal and ranking, but
+never surfaces.
+
+---
+
+## 4. Ambiguity produces a diagnostic, never a guess
+
+**Decision.** When a call's receiver is unresolved and several methods share the
+name, add **no edge** and record `unresolved_method_receiver`. Only a unique name
+match earns a `medium` edge.
+
+**Why.** This is the decision the whole product rests on. A user who finds one
+confidently-asserted, obviously-wrong edge will stop trusting every other edge —
+and correctly so. False negatives are disappointing; confident false positives are
+disqualifying.
+
+**Cost.** RippleEffect misses real relationships in codebases that use common
+method names heavily.
+
+**Mitigation.** The diagnostic is visible with `--verbose`, so a user can see
+exactly what was skipped and why.
+
+---
+
+## 5. Edges point from dependent to dependency
+
+**Decision.** `from_id` depends on `into_id`, always, with no exceptions.
+
+**Why.** A graph that mixes directions is unusable: every traversal has to know
+which convention each edge type follows. With one rule, "what breaks if I change
+this?" is simply a reverse walk.
+
+**Cost.** Some edges read backwards at first (a route "depends on" its controller
+action; a class "depends on" the methods it defines). The consistency is worth it.
+
+---
+
+## 6. Breadth-first traversal
+
+**Decision.** Breadth-first, keeping the shortest path, breaking ties on
+confidence.
+
+**Why.** The evidence path is the product. The shortest chain of reasoning is the
+one a human can verify fastest, and verifiability is what makes the output
+trustworthy. Depth-first would produce arbitrary, sometimes very long,
+explanations for the same conclusion.
+
+**Cost.** Slightly more bookkeeping: an equally-short alternative path must still
+reach the tie-break even though it is not re-queued.
+
+---
+
+## 7. Diff maps lines to the smallest enclosing declaration
+
+**Decision.** Map changed line ranges to the innermost declaration, rather than
+marking every declaration in a touched file as changed.
+
+**Why.** File-level granularity makes a one-line fix look like a rewrite of the
+class, which makes the entire blast radius useless in exactly the case people care
+about most.
+
+**Cost.** Real complexity. Deleted code exists only in the base revision, so it
+must be fetched with `git show` and parsed separately. When a deleted symbol is
+gone entirely, the change is attributed to its former owner: which is what its
+dependents actually referenced.
+
+---
+
+## 8. `tests` refuses to narrow after a global-file change
+
+**Decision.** When a boot-impact file changes, print nothing to stdout and exit
+`2` unless `--allow-unsafe-focus` is given.
+
+**Why.** Printing a short list is an implicit claim that the omitted tests are
+unnecessary. For a change to `config/initializers/` or the `Gemfile`, the graph
+cannot support that claim. Since the output is designed to be piped straight into
+`rspec`, a quiet under-approximation would silently skip tests in CI.
+
+**Cost.** An extra flag for users who know what they are doing.
+
+**Principle.** RippleEffect can show a test is probably relevant. It cannot show
+one is irrelevant.
+
+---
+
+## 9. Structural edges exist, but are hidden from text output
+
+**Decision.** Keep `file -> class` and `class -> method` edges in the graph; hide
+them in text output; keep them in JSON.
+
+**Why.** They are load-bearing: a file-level diff needs to reach the code it
+declares, and a method change needs to reach dependents of its class. But
+reporting "app/models/order.rb depends on Order#total" as a *finding* buries the
+real answer under noise.
+
+**Cost.** Text and JSON differ in content, which must be documented. Risk scoring
+also has to exclude file nodes, or every score inflates with the number of files
+touched.
+
+---
+
+## 10. JSON cache, never Marshal
+
+**Decision.** Serialise the graph cache as JSON.
+
+**Why.** A cache file is ordinary data in `tmp/` that any process can write.
+`Marshal.load` on untrusted data constructs arbitrary objects. The performance
+difference does not come close to justifying that.
+
+**Cost.** Slower serialisation, and value objects must be reconstructed by hand on
+read.
+
+---
+
+## 11. Cache keyed on full content digests
+
+**Decision.** SHA-256 every indexed file into the cache key, rather than relying on
+mtime and size.
+
+**Why.** A stale graph produces a *wrong answer that looks right*, which is the
+worst failure mode this tool has. Branch switching, `git stash` and checkouts all
+move mtimes in ways that make timestamp invalidation unreliable.
+
+**Cost.** Hashing every file on every run.
+
+**Escape hatches.** A corrupt cache is discarded and rebuilt rather than being
+fatal; `--no-cache` skips it entirely.
+
+---
+
+## 12. OptionParser rather than Thor
+
+**Decision.** Use the standard library.
+
+**Why.** Adding a runtime dependency to a developer tool means adding it to every
+project that installs the tool. OptionParser is adequate for six subcommands.
+
+**Cost.** Subcommand dispatch and shared-flag handling written by hand: about
+sixty lines in `CLI::Command`.
+
+---
+
+## 13. Rails is analysed, never depended on
+
+**Decision.** No Rails dependency, at any version.
+
+**Why.** Loading Rails to analyse Rails would mean booting the target
+application: the exact thing that makes this kind of tool slow, fragile, and
+unsafe on an unfamiliar codebase. Static analysis also works on a broken app,
+which is often when you most want it.
+
+**Cost.** Rails' inflections and conventions are reimplemented in miniature. The
+inflector is small and conservative, and an unresolved target is
+reported rather than guessed.