Skip to content
dpepPublic

About

Ruby structural search and rewrites

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

rwr

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 fixtures

What makes it different

It 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_name

That 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.

Install

cargo install rwr

The built-in pack

A 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 rule

style/ 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.

Rules

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.

Templates

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.

For agents, hooks and CI

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.

Scope

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.

Performance

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.

Shell completions

rwr --completions            # the shell you are in
rwr --completions zsh        # or name one: bash, zsh, fish, elvish, powershell

Bare --completions reads $SHELL, since naming your own shell to a tool already running inside it is friction with no purpose.

Documentation

Design notes and research, kept because the reasoning is worth having:

License

MIT

About

Ruby structural search and rewrites

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages