Query Method Calls from Ruby Programs
Querly is a query language and tool to find out method calls from Ruby programs. Define rules to check your program with patterns to find out bad pieces. Querly finds out matching pieces from your program.
Your project may have many local rules:
Customer#update_mailand use 30x faster
Customer.update_all_emailinstead (Slower
#update_mailis left just for existing code, but new code should not use it)
root_urlwithout
locale:parameter
Net::HTTPfor Web API calls, but use
HTTPClient
These local rule violations will be found during code review. Reviewers will ask commiter to revise; commiter will fix; fine. Really? It is boring and time-consuming. We need some automation!
However, that rules cannot be the standard. They make sense only in your project. Okay, start writing a plug-in for RuboCop? (or other checking tools)
Instead of writing RuboCop plug-in, just define a Querly rule in a few lines of YAML.
rules: - id: my_project.use_faster_email_update pattern: update_mail message: When updating Customer#email, newly written code should use 30x faster Customer.update_all_email justification: - When you are editing old code (it should be refactored...) - You are sure updating only small number of customers, and performance does not matter
id: my_project.root_url_without_locale pattern: "root_url(!locale: _)" message: Links to top page should be with locale parameter
id: my_project.net_http pattern: Net::HTTP message: Use HTTPClient to make HTTP request
Write down your local rules, and let Querly check conformance with them. Focus on spec, design, UX, and other important things during code review!
Install via RubyGems.
$ gem install querly
Or you can put it in your Gemfile.
gem 'querly'
Copy the following YAML and paste as
querly.ymlin your project's repo.
rules: - id: sample.debug_print pattern: - self.p - self.pp message: Delete debug print
Run
querlyin the repo.
$ querly check .
If your code contains
por
ppcalls, querly will print warning messages.
./app/models/account.rb:44:10 p(account.id) Delete debug print ./app/controllers/accounts_controller.rb:17:2 pp params: params Delete debug print
See the following manual for configuration and query language reference.
Use
querly consolecommand to test patterns interactively.
importsection in config file now allows accepts
requirecommand.
import: - require: querly/rules/sample - require: your_library/querly/rules
Querly ships with
querly/rules/samplerule set. Check
lib/querly/rules/sample.rband
rules/sample.ymlfor detail.
Querly provides
Querly.load_ruleAPI to allow publishing your rules as part of Ruby library. Put rules YAML file in your gem, and add Ruby script in some directory like
lib/your_library/querly/rules.rb.
Querly.load_rules File.join(__dir__, relative_path_to_yaml_file)
The analysis is currently purely syntactic:
record.save(validate: false)
and
x = false record.save(validate: x)
will yield different results. This can be improved by doing very primitive data flow analysis, and I'm planning to do that.
The analysis itself does not have very good precision. There will be many false positives, and querly warning free code does not make much sense.
Querly is not to ensure there is nothing wrong in the code, but just tells you code fragments you should review with special care. I believe it still improves your software development productivity.
The following is the list of updates which would make sense.
After checking out the repo, run
bin/setupto install dependencies. Then, run
rake testto run the tests. You can also run
bin/consolefor an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gemfile to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/soutaro/querly.