HackMD
RBS Rails current state and the future
This document describes the design of rbs_rails gem, and the future works.
It also describes Rails-related gems' RBS files in ruby/gem_rbs_collection repository.
RBS files in gem_rbs_collection
work with RBS Rails
Some classes, modules, and interfaces are depend on RBS Rails. Be careful to introduce breaking changes to them.
Generated RBS files
Currently this repository contains generated and hand-written RBS files. I want to distinguish them to run the generator continuously, but unfortunately they are mixed.
In the future, probably unifying these files is better. We do not need to distinguish generated and hand-written files.
But probably we need to distinguish patch.rbs because the patch.rbs file contains RBS that is not for the gem itself, but other dependencies.
Public API and Private API
As I mentioned the previous section, the RBS files are generated. They contain not only public APIs but also private APIs.
I think we can drop RBS definitions for private APIs. They are unnecessary information for Rails user. They also make the RBS file larger. We can keep the RBS files slim by removing unnecessary definitions.
I'm concerning that some private APIs are actually used by the user… Probably we need to leave some private API.
Design
This section describes the design of RBS Rails gem.
Rails related gems
Such as action_args.
- RBS Rails does not support such gems
- If it supports unofficial gems, the maintenance cost will increase
- Probably plug-in system is a good approach for this problem.
- I've not considered that RBS Rails should treat official but non-default gems, such as jbuilder, propshaft, and so on.
- Not all users use the feature, so plug-in is appropriate…?
- Perhaps RBS Rails does not need to support them if they do not have meta-programming feature such as dynamic method generation.
RBS Rails generates valid standalone RBSs
The generated RBS files by RBS Rails should be valid only with the Rails related RBS files in ruby/gem_rbs_collection.
It means the user does not need to write RBS definition to make the generated RBS valid.
"valid" means rbs validate command passes
Generate RBS as a String
RBS Rails construct RBS content as a String.
We can also construct with RBS AST, but I think it is over-engineering. String construction is enough in this case.
But probably it should escape correctly, such as method name. Probably we can solve this problem with using RBS::Writer partially.
Future
This section describes what I want to achieve by RBS Rails in the future.
Define methods in right places
Currently, the generated method is defined in a pseudo module. It introduces some problems, so we should define these method in the right places.
path helper
I didn't focus on it. Currently RBS Rails generates type definitions for path helpers, but actually it is not utilized. Probably we can improve it.
How to fetch metadata from Rails
Currently, RBS Rails fetches metadata with two ways. They are static and dynamic analysis.
In short, we should remove static analysis because it is incomplete.
For example, currently RBS Rails uses static analysis to get enum metadata.
https://github.com/pocke/rbs_rails/blob/4ba3f0fa61f961590213cc04e83a5433166691ed/lib/rbs_rails/active_record.rb#L356-L359
It's because Rails does not store enough information to construct the RBS definitions.
But the static analysis has a problem. It does not work on enum definitions in another files. For example:
# publishable.rb
module Publishable
extend AS::Concern
included do
enum state: { draft: 1, published: 2 }
end
end
# note.rb
class Note < ApplicationRecord
include Publishable
end
In the above case, RBS Rails does not detect state enum because RBS Rails only parse note.rb but the enum defined in publishable.rb.
To solve this problem, I think we need to introduce dynamic analysis with different approach with other features. We can add a module to override tne enum method. For example:
module EnumInspection
def enum(entry)
store_the_enum_entry entry
super
end
end
ActiveRecord::Base.singleton_class.prepend EnumInspection
It can use the data that enum method received, so it has enough information to generate RBS definitions. It also depends only on public APIs, so it is stable.
However, I'm concerning that there is a right timing to prepend the module. This module should be prepended before evaluating all user defined code.
Perhaps we can replace other dynamic analysis with this solution. Such as has_many. I think the prepending solution is better if the dynamic analysis depends on a Rails private API. We need to research that RBS Rails depends on private APIs or not.
