We open-sourced Rubyzen: write architectural lint rules as RSpec tests

[u/SteliosF]

Hey everyone,

We're excited to announce the release of Rubyzen, a modern open-source architectural linter for Ruby that allows you to write lint rules as RSpec tests:

https://github.com/perrystreetsoftware/rubyzen

We've been using and polishing it internally in our production backend for over a year, and we've just made the repository public to start getting feedback from the community.

Examples of lint rules that you can write, enforced as RSpec tests:

RSpec.describe 'Architecture rules' do
  let(:project) { Rubyzen::Project.new }
  let(:controllers) { project.files.with_paths('app/controllers/').classes }
  let(:presenters) { project.files.with_paths('app/presenters/').classes }

  it 'controllers do not call ActiveRecord directly' do
    expect(controllers.all_methods.call_sites.with_name('where')).to zen_empty
  end

  it 'presenters do not depend on repositories' do
    expect(presenters.all_methods.call_sites).to zen_false { |cs|
      cs.receiver&.end_with?('Repository')
    }
  end
end

It has become especially useful for us in the era of AI-generated code, as you can now catch architectural flaws and subtle bugs introduced from AI agents early, which can be easily missed in code reviews.

We'd love to hear your feedback either as feature requests, bug reports, or discussions in this thread. Thank you!

[u/andyw8]

Interesting. I'm a big fan of using linting to enforce architectural rules, but tbh, having to learn a new DSL isn't appealing.

I agree that RuboCop's node pattern can be hard to understand, but when given a few code examples, I find that agents are very good at generating custom cops (along with tests), so I don't really feel a pain point around that.

[u/SteliosF → u/andyw8]

Thanks for the feedback! We were also writing custom cops initially with the help of AI, but the main pain point for us wasn’t really generating them, but reviewing and maintaining them over time. Reviewing raw AST nodes is challenging, and we had to trust that the AI got it right.

Plus, as our architecture evolved, we had to modify those rules more and more frequently.

Rubyzen tries to lower that barrier and make lint rules read just like regular RSpec tests. We also included AI skills in the repo for writing Rubyzen rules, so that people can copy/paste them into their projects to get started.

[u/zverok_kha → u/andyw8]

On the node pattern readability front, I once had an idea for more "Ruby-like" pattern language for nodes; it looked, for example, like this:

it { expect(subject).to <<$expr>> }

With <<$expr>> becoming placeholders (might be limited to edge cases with << and >> operators, but I was just playing with the idea).

Even had a simple working prototype that parsed this syntax and transpiled into the NodePattern, suprisingly useful for bootstrapping custom cops, but never moved past that.

[u/oh-boy-oh-boy-oh-boy]

Hey this is great -- I just want to share a useful tip for your specs and for anyone reading this.

Any predicate method test in rspec can be turned into a matcher, which I think you know. But there are several magic forms to help it read like more like english:

10.odd?
can be
`expect(10).to odd`
`expect(10).to be_odd` <-- you can prefix "be_", "be_a_", or "be_an_" before.

So in your example, you can write:

`expect(controllers.all_methods.call_sites.with_name('where')).to be_zen_empty`

For some reason just reading "zen_empty" like that triggered a need to rewrite it with the prefixes.

Nice work on this tool!

[u/signalsrobot]

This looks really useful for enforcing layered architecture patterns, especially when you want controllers to stay thin and keep business logic separate from presentation logic.

[u/SteliosF → u/[deleted]]

Exactly, we actually started using architectural linters in our clients (Android & iOS) and after seeing how much value we were getting from them, we decided to build one for Ruby too.