Querly - Pattern Based Checking Tool for Ruby

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.

Overview

Your project may have many local rules:

• Should not use

  Customer#update_mail

  and use 30x faster

  Customer.update_all_email

  instead (Slower

  #update_mail

  is left just for existing code, but new code should not use it)
• Should not use

  root_url

  without

  locale:

  parameter
• Should not use

  Net::HTTP

  for 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!

Installation

Install via RubyGems.

$ gem install querly

Or you can put it in your Gemfile.

gem 'querly'

Quick Start

Copy the following YAML and paste as

querly.yml

rules:
  - id: sample.debug_print
    pattern:
      - self.p
      - self.pp
    message: Delete debug print

Run

querly

$ querly check .

If your code contains

p

pp

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

Configuration

See the following manual for configuration and query language reference.

• Configuration
• Patterns

Use

querly console

Requiring Rules

import

require

import:
  - require: querly/rules/sample
  - require: your_library/querly/rules

Querly ships with

querly/rules/sample

lib/querly/rules/sample.rb

rules/sample.yml

Publishing Gems with Querly Rules

Querly provides

Querly.load_rule

lib/your_library/querly/rules.rb

Querly.load_rules File.join(__dir__, relative_path_to_yaml_file)

Notes

Querly's analysis is syntactic

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.

Too many false positives!

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.

• TODO: support to ignore warnings through magic comments in code

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.

Incoming updates?

The following is the list of updates which would make sense.

• Support for importing rule sets, and provide some good default rules
• Support for ignoring warnings
• Improve analysis precision by intra procedural data flow analysis

Development

After checking out the repo, run

bin/setup

rake test

bin/console

To install this gem onto your local machine, run

bundle exec rake install

version.rb

bundle exec rake release

.gem

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/soutaro/querly.