A power tool for refactoring Ruby codebases — a scalpel at scale. Precision normally means one file at a time; scale normally means a regex you hope is right. rwr declines the trade: it matches the parse tree, so a rename across ten thousand files is as exact as one done by hand.
Ruby structural search and rewrites — rg/sed for Ruby programs rather than
Ruby text.
Find code by structure, rewrite only what matches, preserve everything else, and refuse when it can't be sure.
rwr 'return nil' # find, whole repo
rwr 'return nil' app/models # find, scoped
rwr '$R.select { |$P| $B }.first' # metavariables
rwr check all app/ # every built-in rule, read-only
rwr check all --since main # only the lines this branch touched
rwr check all app/x.rb:3-15 # only those lines
rwr rewrite rule.yml app/ # apply
rwr rewrite 'def legacy(*$A); $B; end' -d # delete, doc comment and all
rwr test my-rules/ # run the rules' own fixturesIt knows what a receiver is. Renaming Account#display_name leaves
Company#display_name and Account.display_name alone — they are different
methods. No other Ruby structural tool does this: node_pattern has no notion
of a receiver, ast-grep's FAQ disclaims type analysis, and Ruby LSP matches
methods by bare name.
rwr find 'Account#display_name' app/ # read-only: where is this method?method: Account#display_name
rename: full_nameThat reaches the definition, an override in a subclass, explicit-receiver calls,
and implicit-self calls — and nothing else. All three verbs read that notation
and name the same sites, so a preview cannot cover less than the apply;
rwr rewrite 'Account#display_name' -r full_name app/ is the whole rename with
no file at all. Where a repository has Sorbet signatures, sig { returns(X) } is
read as a return type, so a chain like parser.document.name resolves too — no
RBI parser, no new file format, just Ruby already in the tree. On one real
monolith 76% of methods carry a signature.
An unqualified class name means the class of exactly that name if the run can see
one, and otherwise the single class whose qualified name ends with it. Where
several do — nine …::LogSubscribers and no plain one — it means none of them,
because choosing between ActiveSupport::LogSubscriber and
ActionView::LogSubscriber is precisely the wrong rewrite this tool exists to
refuse. Qualify the name to say which you meant.
It tells you what it missed. Ruby dispatches through symbols, so a rename
that reaches only call sites leaves attr_accessor :display_name behind and the
class breaks. rwr moves the symbols that name the method, and everything it
cannot account for it names rather than guessing at:
app/models/account.rb: rewrote 2 site(s)
3 occurrence(s) `Account#display_name` could not account for (1 symbol, 1 call, 1 comment):
app/jobs/sync.rb:3:5: Call: thing.display_name
app/models/account.rb:5:12: Symbol: delegate :display_name, to: :profile
app/models/account.rb:8:19: Comment: # Returns the display_name
Each of those is a judgement a symbol cannot settle. delegate forwards to
another class, so whether that class's method should move too is not rwr's
call. thing's type never resolves, so the receiver might be any class that
happens to share the name. And comments are reported but never rewritten:
# See also #display_name on Company is about a different class, and nothing in
the prose says so.
Its diffs are minimal. Only what changed moves. Layout, block spelling and heredocs survive, because an unchanged subtree is never spliced.
It refuses rather than guesses. Ambiguity produces a diagnostic and zero
edits. A comment that cannot be unambiguously attached to a reordered element
declines with the source untouched; a deletion whose match does not occupy whole
lines is refused, since removing a.name from x = a.name leaves x = , which
swallows the line below and still parses.
cargo install rwrA set of rules ships compiled into the binary, so it runs from any directory:
rwr check all app/ # every safe rule
rwr check performance app/ # one family
rwr check style/return-nil app/ # one rulestyle/ covers things like return nil and hash shorthand; performance/
covers detect, filter_map, sum, gsub → tr, and the ActiveRecord set —
where(...).count > 0 → exists?, find_by, pluck.
Rules that can change behaviour are held back, and the run says how many —
-e says which and why. inject(:+) returns nil for an empty collection where
sum returns 0; select on an ActiveRecord relation names columns rather than
filtering rows. --unsafe includes them and prints each caveat after the run.
Rules also declare the Ruby version their output needs, and are held back on an
older codebase — {foo:} is a syntax error before 3.1, and no amount of
verification catches that, because Prism parses the output happily. The version
comes from .ruby-version, a Gemfile ruby line or a gemspec; --ruby X.Y
overrides. An undetected version holds the rules back rather than assuming the
newest.
There are no per-rule options. A cop needs configuring because it is opaque
code; an rwr rule is four lines of YAML, so the rule is the option — to get
the other direction, copy the file and swap match with rewrite. See
rules/README.md.
A rule is Ruby source with $METAVARS, plus constraints source syntax cannot
express:
match: $R.$SEL { |$P| $B }.first
where:
$SEL: { name: [select, find_all] } # one rule, both synonyms
rewrite: $R.detect { |$P| $B }| one node | zero or more | |
|---|---|---|
| anonymous | _ |
*_ |
| captured | $NAME |
*$NAME |
All four are valid Ruby, so the language's own grammar validates where a sequence may appear.
where: also carries type:/kind:/subclasses: (receiver narrowing),
same_name_as: (two captures naming one identifier across node kinds), and
is:/length: (a capture's node kind and a literal's content) — the pair that
makes gsub → tr safe rather than plausible, since tr maps character by
character.
contains: holds a whole sub-pattern, and shared metavariables have to refer to
the same thing:
match: $R.each { |$X| $B }
where:
$B: { contains: $X.$ASSOC.$FIELD }That is performance/possible-n-plus-one, which narrows discourse's 637
each/map blocks to 51 candidates.
A rule with no rewrite: is a finding. It reports its matches with its
description and proposes nothing, for shapes where the right answer depends on
something rwr cannot see — .size on a relation is count unloaded and length
loaded, and only the caller knows which was meant. Findings make check exit 1
like edits do; a lint that exits 0 gates nothing.
Deletion is -d, or an empty rewrite:; -r '' means the same. Removing a
definition takes the doc comment above it and one of the blank lines that
separated it, so the survivors keep their spacing. Write the parameter list as
(*$A): a pattern matches arity exactly, so def legacy($A) deletes only the
one-parameter version and reports the rest as residue.
A broken rule is refused before a file is read, naming the rule and the reason — an unknown field, a constraint on a capture the pattern never binds, a template metavariable that was never captured, a version string that isn't one.
ERB is parsed, matched and rewritten. Tag bodies are stitched into a single Ruby program — 95% of real templates parse that way — so a rename reaches inside a view and leaves every byte of HTML where it was. An edit spanning two tags is refused, since the bytes between them are not Ruby.
Haml is not parsed. Templates rwr cannot parse are text-searched at whole-identifier boundaries and reported as their own class: grep-grade evidence, labelled as weaker than anything parsed, because a call site missing from the account is the dangerous direction.
Everything that prints honors -j/--json, which emits one document —
{schema, rwr_version, changed, findings, residue, template_residue, templates_skipped, unparsed, unreadable, suppressed, stale_suppressions, unknown_suppressions, malformed_directives},
with find carrying matches and interpreted where the writing verbs carry
changed and findings. -J/--ndjson is that same document on one line, for
every verb.
Prefer either over the text output in a script. In text mode the matches and the
per-file counts go to stdout and the account of what rwr could not see goes to
stderr, so a caller that captures stdout alone reads rewrote 3 site(s), exit 0,
and never learns which sites need a human.
Scoping a run to the lines a change touched is what makes check adoptable on a
codebase that has never run it: three new sites fail, two thousand pre-existing
ones do not.
| Scope | |
|---|---|
--diff |
what is not committed yet, untracked files included — the pre-commit case |
--since main |
what this branch introduces, main...HEAD — the CI case, where --since "origin/$GITHUB_BASE_REF" is the recipe |
--since main --diff |
both: the merge base against the working tree |
app/x.rb:3-15 |
those lines, named directly. :3 is a single line, and it is the file:line rwr prints |
--diff takes no value: as --diff [<REV>] it swallowed a following path as its
revision, and deciding by whether that path exists on disk would be a guess.
Exit codes, which a caller can branch on before parsing any output:
find |
check |
rewrite |
|
|---|---|---|---|
| 0 | matched | clean | applied, or nothing to do |
| 1 | no match | work to do | — |
| 2 | error | error | error |
| 3 | the rule is wrong | the rule is wrong | the rule is wrong |
| 4 | — | — | retryable — rerun makes progress |
| 5 | refused — needs judgement | refused | refused |
check inverts polarity deliberately: a clean tree is success, so a pre-commit
hook does not block a commit where a rule correctly matches nothing.
rwr does not own style. Indentation and trailing commas are presentation — a trailing comma is invisible to rwr's own equality — so they belong to a formatter. rwr repairs what it disturbs and shells out for the rest.
Also out of reach: non-anchored insertions, coordinated multi-site edits, and
sub-identifier name transforms (find_by_*). See DESIGN.md.
rwr is not a RuboCop replacement. RuboCop owns the standing community rule corpus; rwr is for one-off migrations that do not deserve a cop class, and for rules RuboCop cannot express because its patterns are purely syntactic.
Cost tracks how many files mention an identifier, not repository size: a literal
prefilter skips any file that cannot contribute. Over discourse's 11,006 files,
five warm runs — find on a single pattern 175 ms, a rename 292 ms, the
pack's safe rules 478 ms, each discovering, reading, searching, parsing the
survivors and matching structurally. --unsafe, which runs every rule in the
pack rather than only those that need no caveat, takes about 1.4 s.
--profile reports where the time went. See docs/internal/scaling.md.
rwr --completions # the shell you are in
rwr --completions zsh # or name one: bash, zsh, fish, elvish, powershellBare --completions reads $SHELL, since naming your own shell to a tool
already running inside it is friction with no purpose.
- docs/ — the guides: GitHub Actions, getting started, writing rules, suppressing findings
- rules/README.md — the shipped pack and its safety notes
- claude/INSTALL.md — installing the Claude skill, which teaches an agent to drive rwr
Design notes and research, kept because the reasoning is worth having:
- DESIGN.md — what it is and how it works
- docs/internal/architecture.md — how the pieces fit, for feature work
- docs/internal/decisions.md — every decision, and what would reverse it
- docs/internal/cli-conventions.md — the output and exit-code contract
- docs/internal/phase0-conclusion.md — whether this should exist, and the evidence
- docs/internal/scaling.md — the cost model, measured
- docs/internal/prior-art.md — ast-grep, Comby, Semgrep, RuboCop, Ruby LSP
MIT