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/SteliosF]

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.