querly 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 98d2102a17e63b28b3c08366d02b7e54c804d8c8
-  data.tar.gz: a152411cc3e70cd97fac3534c950c16c62d955d1
+  metadata.gz: 2a7dfd2ae45b1173ea9e23967e5c39b211bebffb
+  data.tar.gz: d014023c1f6e4d6989d04ea688dbaad0fed475ba
 SHA512:
-  metadata.gz: 903128838bc67d5296f269ceffc1b3e42eedb982e917064351607fb652171bfc29e2bc3c2ce7c8faac1338b11d56ff82fa6fcfe16c6e06a382907affb871f19f
-  data.tar.gz: d0aeabc064163ae7630f007e7756f88932ed6c555bb4e864aeb23bf350f1ad62d6765d43b51d6010d4851d3f9653b0cfc7a7c5515164aebf84e143e87d5de313
+  metadata.gz: 54969626459f41a814877e188ee487a911f01cbe9a17fe83ed2ed8b110736be3088994c2c0e73754c418c93e37e640fe409707740edd9245f63adc7d09045cf0
+  data.tar.gz: 100d7dbc6eb4dc7a6edadd86c08760782aa4ab65f1b4958d1b1e3f6360a2db28b00b748297367dd7df47caef9259b7b93f13b3a4f6ffc57dc694c785dcb49332

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## master
 
+## 0.7.0 (2017-08-22)
+
+* Add Wiki pages to repository in manual directory #25
+* Add named literal pattern `:string: as 'name` with `where: { name: ["alice", /bob/] }` #24
+* Add `init` command #28
+
 ## 0.6.0 (2017-06-27)
 
 * Load current directory when no path is given (@wata727) #18

data/README.md

@@ -87,10 +87,10 @@ If your code contains `p` or `pp` calls, querly will print warning messages.
 
 ## Configuration
 
-Visit our wiki pages for configuration and query language reference.
+See the following manual for configuration and query language reference.
 
-* [Configuration](https://github.com/soutaro/querly/wiki/Configuration)
-* [Patterns](https://github.com/soutaro/querly/wiki/Patterns)
+* [Configuration](https://github.com/soutaro/querly/blob/master/manual/configuration.md)
+* [Patterns](https://github.com/soutaro/querly/blob/master/manual/patterns.md)
 
 Use `querly console` command to test patterns interactively.
 

data/lib/querly/cli.rb

@@ -86,6 +86,17 @@ Specify configuration file by --config option.
       puts "Querly #{VERSION}"
     end
 
+    def self.source_root
+      File.join(__dir__, "../..")
+    end
+
+    include Thor::Actions
+
+    desc "init", "Generate Querly config file (querly.yml)"
+    def init()
+      copy_file("template.yml", "querly.yml")
+    end
+
     private
 
     def config_path

data/lib/querly/pattern/expr.rb

@@ -23,7 +23,7 @@ module Querly
 
       class Any < Base
         def test_node(node)
-          true
+          !!node
         end
       end
 
@@ -81,56 +81,53 @@ module Querly
 
       class Literal < Base
         attr_reader :type
-        attr_reader :value
+        attr_reader :values
 
-        def initialize(type:, value: nil)
+        def initialize(type:, values: nil)
           @type = type
-          @value = value
+          @values = values ? Array(values) : nil
+        end
+
+        def with_values(values)
+          self.class.new(type: type, values: values)
+        end
+
+        def test_value(object)
+          if values
+            values.any? {|value| value === object }
+          else
+            true
+          end
         end
 
         def test_node(node)
           case node&.type
           when :int
             return false unless type == :int || type == :number
-            if value
-              value == node.children.first
-            else
-              true
-            end
+            test_value(node.children.first)
 
           when :float
             return false unless type == :float || type == :number
-            if value
-              value == node.children.first
-            else
-              true
-            end
+            test_value(node.children.first)
 
           when :true
-            type == :bool && (value == nil || value == true)
+            type == :bool && (values == nil || values == [true])
 
           when :false
-            type == :bool && (value == nil || value == false)
+            type == :bool && (values == nil || values == [false])
 
           when :str
             return false unless type == :string
-            if value
-              value == node.children.first
-            else
-              true
-            end
+            test_value(node.children.first)
 
           when :sym
             return false unless type == :symbol
-            if value
-              value == node.children.first
-            else
-              true
-            end
+            test_value(node.children.first)
 
           when :regexp
             type == :regexp
-            
+            test_value(node.children.first)
+
           end
         end
       end
@@ -162,7 +159,14 @@ module Querly
         end
 
         def test_name(node)
-          name.any? {|n| n === node.children[1] }
+          name.map do |n|
+            case n
+            when String
+              n.to_sym
+            else
+              n
+            end
+          end.any? {|n| n === node.children[1] }
         end
 
         def test_node(node)

data/lib/querly/pattern/parser.y

@@ -17,19 +17,23 @@ expr: constant { result = Expr::Constant.new(path: val[0]) }
   | send
   | SELF { result = Expr::Self.new }
   | EXCLAMATION expr { result = Expr::Not.new(pattern: val[1]) }
-  | BOOL { result = Expr::Literal.new(type: :bool, value: val[0]) }
-  | STRING { result = Expr::Literal.new(type: :string, value: val[0]) }
-  | INT { result = Expr::Literal.new(type: :int, value: val[0]) }
-  | FLOAT { result = Expr::Literal.new(type: :float, value: val[0]) }
-  | SYMBOL { result = Expr::Literal.new(type: :symbol, value: val[0]) }
-  | NUMBER { result = Expr::Literal.new(type: :number, value: val[0]) }
-  | REGEXP { result = Expr::Literal.new(type: :regexp, value: nil) }
+  | BOOL { result = Expr::Literal.new(type: :bool, values: val[0]) }
+  | literal { result = val[0] }
+  | literal AS META { result = val[0].with_values(resolve_meta(val[2])) }
   | DSTR { result = Expr::Dstr.new() }
   | UNDERBAR { result = Expr::Any.new }
   | NIL { result = Expr::Nil.new }
   | LPAREN expr RPAREN { result = val[1] }
   | IVAR { result = Expr::Ivar.new(name: val[0]) }
 
+literal:
+    STRING { result = Expr::Literal.new(type: :string, values: val[0]) }
+  | INT { result = Expr::Literal.new(type: :int, values: val[0]) }
+  | FLOAT { result = Expr::Literal.new(type: :float, values: val[0]) }
+  | SYMBOL { result = Expr::Literal.new(type: :symbol, values: val[0]) }
+  | NUMBER { result = Expr::Literal.new(type: :number, values: val[0]) }
+  | REGEXP { result = Expr::Literal.new(type: :regexp, values: nil) }
+
 args:  { result = nil }
   | expr { result = Argument::Expr.new(expr: val[0], tail: nil)}
   | expr COMMA args { result = Argument::Expr.new(expr: val[0], tail: val[2]) }
@@ -55,6 +59,7 @@ key_value: keyword COLON expr { result = { key: val[0], value: val[2], negated:
 
 method_name: METHOD
   | EXCLAMATION
+  | AS
   | META { result = resolve_meta(val[0]) }
 
 method_name_or_ident: method_name
@@ -66,10 +71,10 @@ keyword: LIDENT | UIDENT
 constant: UIDENT { result = [val[0]] }
   | UIDENT COLONCOLON constant { result = [val[0]] + val[2] }
 
-send: LIDENT block { result = val[1] != nil ? Expr::Send.new(receiver: Expr::Any.new, name: val[0], args: Argument::AnySeq.new, block: val[1]) : Expr::Vcall.new(name: val[0]) }
-  | UIDENT block { result = Expr::Send.new(receiver: Expr::Any.new, name: val[0], block: val[1]) }
-  | method_name { result = Expr::Send.new(receiver: Expr::Any.new, name: val[0], block: nil) }
-  | method_name_or_ident LPAREN args RPAREN block { result = Expr::Send.new(receiver: Expr::Any.new,
+send: LIDENT block { result = val[1] != nil ? Expr::Send.new(receiver: nil, name: val[0], args: Argument::AnySeq.new, block: val[1]) : Expr::Vcall.new(name: val[0]) }
+  | UIDENT block { result = Expr::Send.new(receiver: nil, name: val[0], block: val[1]) }
+  | method_name { result = Expr::Send.new(receiver: nil, name: val[0], block: nil) }
+  | method_name_or_ident LPAREN args RPAREN block { result = Expr::Send.new(receiver: nil,
                                                                             name: val[0],
                                                                             args: val[2],
                                                                             block: val[4]) }
@@ -122,9 +127,9 @@ def next_token
   case
   when input.eos?
     [false, false]
-  when input.scan(/true/)
+  when input.scan(/true\b/)
     [:BOOL, true]
-  when input.scan(/false/)
+  when input.scan(/false\b/)
     [:BOOL, false]
   when input.scan(/nil/)
     [:NIL, false]
@@ -147,6 +152,8 @@ def next_token
   when input.scan(/:\w+/)
     s = input.matched
     [:SYMBOL, s[1, s.size - 1].to_sym]
+  when input.scan(/as\b/)
+    [:AS, :as]
   when input.scan(/{}/)
     [:WITH_BLOCK, nil]
   when input.scan(/!{}/)

data/lib/querly/pp/cli.rb

@@ -55,27 +55,20 @@ module Querly
 
       def run_haml
         require "haml"
-        if Haml::VERSION >= '5.0.0'
-          raise <<~ERROR
-            HAML 5.0+ is detected.
-            `querly-pp haml` does not work on HAML 5.0+.
-            Use `haml -d` instead.
-          ERROR
-        end
-
         load_libs
-
         source = stdin.read
 
-        options = Haml::Options.new
-
-        parser = Haml::Parser.new(source, options)
-        parser.parse
-
-        compiler = Haml::Compiler.new(options)
-        compiler.compile(parser.root)
+        if Haml::VERSION >= '5.0.0'
+          stdout.print Haml::Engine.new(source).precompiled
+        else
+          options = Haml::Options.new
+          parser = Haml::Parser.new(source, options)
+          parser.parse
+          compiler = Haml::Compiler.new(options)
+          compiler.compile(parser.root)
 
-        stdout.print compiler.precompiled
+          stdout.print compiler.precompiled
+        end
       end
     end
   end

data/lib/querly/rule.rb

@@ -116,7 +116,7 @@ module Querly
         when /\A\/(.*)\/\Z/
           Regexp.new($1)
         else
-          v.to_sym
+          v
         end
       end
     end

data/lib/querly/script_enumerator.rb

@@ -11,11 +11,10 @@ module Querly
     def each(&block)
       if block_given?
         paths.each do |path|
-          case
-          when path.file?
-            load_script_from_path path, &block
-          when path.directory?
+          if path.directory?
             enumerate_files_in_dir(path, &block)
+          else
+            load_script_from_path path, &block
           end
         end
       else

data/lib/querly/version.rb

@@ -1,3 +1,3 @@
 module Querly
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/manual/configuration.md

@@ -0,0 +1,94 @@
+# Overview
+
+The configuration file, default name is `querly.yml`, will look like the following.
+
+```yml
+rules:
+  ...
+preprocessor:
+  ...
+check:
+  ...
+```
+
+# rules
+
+`rules` is array of rule hash.
+
+```yml
+  - id: com.sideci.json
+    pattern: Net::HTTP
+    message: "Should use HTTPClient instead of Net::HTTP"
+    justification:
+      - No exception!
+    before:
+      - "Net::HTTP.get(url)"
+    after:
+      - HTTPClient.new.get_content(url)
+```
+
+The rule hash contains following keys:
+
+* `id` Identifier of the rule, must be unique (string)
+* `pattern` Patterns to find out (string, or array of string)
+* `message` Error message to explain why the code fragment needs special care (string)
+* `justification` When the *bad use* is allowed (string, or array of string)
+* `before` Sample ruby code to find out (string, or array of string)
+* `after` Sample ruby code to be fixed (string, or array of string)
+
+# preprocessor
+
+When your project contains `.slim`, `.haml`, or any templates which contains Ruby code, preprocessor is to translate the templates to Ruby code.
+`preprocessor` is a hash; key of extension of the templates, value of command line.
+
+```yml
+.slim: slimrb --compile
+.haml: bundle exec querly-pp haml -I lib -r your_custom_plugin
+```
+
+The command will be executed with stdin of template code, and should emit ruby code to stdout.
+
+## querly-pp
+
+Querly 0.2.0 ships with `querly-pp` command line tool which compiles given HAML source to Ruby script.
+`-I` and `-r` options can be used to use plugins.
+
+# check
+
+Define set of rules to check for each file.
+
+```yml
+check:
+  - path: /test
+    rules:
+      - com.acme.corp
+      - append: com.acme.corp
+      - except: com.acme.corp
+      - only: com.acme.corp
+  - path: /test/unit
+    rules:
+      - append:
+          tags: foo bar
+      - except:
+          tags: foo bar
+      - only:
+          tags: foo bar
+```
+
+* `path` Files to apply the rules in `.gitignore` syntax
+* `rules` Rules to check
+
+All matching `check` element against given file name will be applied, sequentially.
+
+* `/lib/bar.rb` => no checks will be applied (all rules)
+* `/test/test_helper.rb` => `/test` check will be applied
+* `/test/unit/account_test.rb` => `/test` and `/test/unit` checks will be applied
+
+## Rules
+
+You can use `append:`, `except:` and `only:` operation.
+
+* `append:` appends rules to current rule set
+* `except:` removes rules from current rule set
+* `only:` update current rule set
+

data/manual/examples.md

@@ -0,0 +1,35 @@
+In this page, I will show some rules I have written. They are all real rules from my repos.
+
+# `js: true` option with feature spec
+
+I see some of Feature Spec scenarios have `js: true` option, and others do not. The reason they look strange to me is some scenarios without `js: true` depend on JavaScript. I changed one of the `js: true` to `js: false`, and run the specs again. They run! What is happening?? The `js` does not stand for *JavaScript*?? What else?
+
+The magic happens in `rails_helper.rb`.
+
+```rb
+Capybara.configure do |config|
+  config.default_driver    = :poltergeist
+  config.javascript_driver = :poltergeist
+end
+```
+
+Okay, `js: true` does not make any sense, because both `default_driver` and `javascript_driver` are same.
+
+Should we fix all of the scenarios now? If we leave them, new teammates will misunderstand `js: true` does something important and required. However, we don't want to fix them now. It does not do anything bad right now. So, my conclusion is *I will do that, but not now* 😸 
+
+It's the time to add a new Querly rule. When someone tries to add new scenario with `js: true`, tell the person that it does not make any sense.
+
+```yaml
+- id: sample.scenario_with_js_option
+  pattern: "scenario(..., js: _, ...)"
+  message: |
+    You do not need js:true option
+
+    We are using Poltergeist as both default_driver and javascript_driver!
+  before:
+    - "scenario 'hello world', js: true, type: :feature do end"
+  after:
+    - "scenario 'foo bar' do end"
+```
+
+No new `js: true` scenario will be written. Our new teammate may try to write that. But Querly will tell they don't have to do that, instead of me.

data/manual/patterns.md

@@ -0,0 +1,168 @@
+# Syntax
+
+## Toplevel
+
+* *expr*
+* *expr* `[` *kind* `]` (kinded expr)
+* *expr* `[!` *kind* `]` (negated kinded expr)
+
+## expr
+
+* `_` (any expr)
+* *method* (method call, with any receiver and any args)
+* *method* `(` *args* `)` *block_spec* (method call with any receiver)
+* *receiver* *method* (method call with any args)
+* *receiver* *method* `(` *args* `)` *block_spec* (method call)
+* *literal*
+* `self` (self)
+* `!` *expr*
+
+### block_spec
+
+* (no spec)
+* `{}` (method call should be with block)
+* `!{}` (method call should not be with block)
+
+### receiver
+
+* *expr* `.` (receiver matching with the pattern)
+* *expr* `...` (some receiver in the chain matching with the pattern)
+
+### Examples
+
+* `p(_)` `p` call with one argument, any receiver
+* `self.p(1)` `p` call with `1`, receiver is `self` or omitted.
+* `foo.bar.baz` `baz` call with receiver of `bar` call of receiver of `foo` call
+* `update_attribute(:symbol:, :string:)` `update_attribute` call with symbol and string literals
+* `File.open(...) !{}` `File.open` call but without block
+
+```rb
+p 1        # p(_) matches
+p 2        # p(_) matches
+p 1, 2, 3  # p(_) does not match
+
+p(1)       # self.p(1) matches
+
+foo(1).bar {|x| x+1 }.baz(3)  # foo.bar.baz matches
+(1+2).foo.bar(*args).baz.bla  # foo.bar.baz matches, partially
+foo.xyz.bar.baz               # foo.bar.baz does not match
+
+update_attribute(:name, "hoge")    # f(:symbol:, :string:) matches
+update_attribute(:name, name)      # f(:symbol:, :string:) does not match
+
+foo.bar.baz               # foo.bar.baz matches
+foo.bar.baz               # foo...baz matches
+bar.foo.baz               # foo...bar...baz does not match
+```
+
+## args & kwargs
+
+### args
+
+* *expr* `,` *args*
+* *expr* `,` *kwargs*
+* *expr*
+* `...` `,` *kwargs* (any argument sequence, followed by keyword arguments)
+* `...` (any argument sequence, including any keyword arguments)
+
+### Literals
+
+* `123` (integer)
+* `1.23` (float)
+* `:foobar` (symbol)
+* `:symbol:` (any symbol literal)
+* `:string:` (any string literal)
+* `:dstr:` (any dstr `"hi #{name}"`)
+* `true`, `false` (true and false)
+* `nil` (nil)
+* `:number:`, `:int:`, `:float:` (any number, any integer, any float)
+* `:bool:` (true or false)
+
+### kwargs
+
+* *symbol* `:` *expr* `,` ...
+* `!` *symbol* `:` *expr* `,` ...
+* `...`
+* `&` *expr*
+
+### Examples
+
+```rb
+f(1,2,3)   # f(...), f(1,2,...), and f(1, ...) matches
+           # f(_,_), f(0, ...) does not match
+
+JSON.load(string, symbolize_names: true)   # JSON.load(..., symbolize_names: true) matches
+                                           # JSON.load(symbolize_names: true) does not match
+
+record.update(email: email, name: name)    # update(name: _, email: _) matches
+                                           # update(name: _) does not match
+                                           # update(name: _, ...) matches
+                                           # update(!id: _, ...) matches
+
+article.try(&:author)        # try(&:symbol:) matches
+article.try(:author)         # try(&:symbol:) does not match
+article.try {|x| x.author }  # try(&:symbol:) does not match
+```
+
+## kind
+
+* `conditional` (When expr appears in *conditional* context)
+* `discarded` (When expr appears in *discarded* context)
+
+Kind allows you to find out something like:
+
+* `save` call but does not check its result for error recovery
+
+*conditional* context is
+
+* Condition of `if` construct
+* Condition of loop constructs
+* LHS of `&&` and `||`
+
+```rb
+# record.save is in conditional context
+unless record.save
+  # error recovery
+end
+
+# record.save is not in conditional context
+x = record.save
+
+# record.save is in conditional context
+record.save or abort()
+```
+
+*discarded* context is where the value of the expression is completely discarded, a bit looser than *conditional*.
+
+```rb
+def f()
+  # record.save is in discarded context
+  foo()
+  record.save()
+  bar
+end
+```
+
+# Difference from Ruby
+
+* Method call parenthesis cannot be omitted (if omitted, it means *any arguments*)
+* `+`, `-`, `[]` or other *operator* should be written as method calls like `_.+(_)`, `[]=(:string:, _)`
+
+# Testing
+
+You can test patterns by `querly console .` command interactively.
+
+```
+Querly 0.1.0, interactive console
+
+Commands:
+  - find PATTERN   Find PATTERN from given paths
+  - reload!        Reload program from paths
+  - quit
+
+Loading... ready!
+> 
+```
+
+Also `querly test` will help you.
+It test configuration file by checking patterns in rules against `before` and `after` examples.

data/template.yml

@@ -0,0 +1,69 @@
+rules:
+  - id: sample.debug_print
+    pattern:
+      - self.p
+      - self.pp
+    message: Delete debug print
+    examples:
+      - before: |
+          pp some: error
+
+  - id: sample.file.open
+    pattern: File.open(...) !{}
+    message: |
+      Use block to read/write file
+
+      If you use block, the open method closes file implicitly.
+      You don't have to close files explicitly.
+    examples:
+      - before: |
+          io = File.open("foo.txt")
+          io.write("hello world")
+          io.close
+        after: |
+          File.open("foo.txt") do |io|
+            io.write("hello world")
+          end
+
+  - id: sample.exception
+    pattern: Exception
+    message: |
+      You probablly should use StandardError
+
+      If you are trying to define error class, inherit that from StandardError.
+    justification:
+      - You are sure you want to define an exception which is not rescued by default
+    examples:
+      - before: class MyError < Exception; end
+        after: class MyError < StandardError; end
+
+  - id: sample.test.assert_equal_size
+    pattern:
+      subject: "assert_equal(:int: as 'zero, _.'size, ...)"
+      where:
+        zero: 0
+        size:
+          - size
+          - count
+    message: |
+      Comparing size of something with 0 can be written using assert_empty
+    examples:
+      - before: |
+          assert_equal 0, some.size
+        after: |
+          assert_empty some.size
+      - before: |
+          assert_equal 0, some.count
+        after: |
+          assert_empty some.count
+
+preprocessor:
+  .slim: slimrb --compile
+
+checks:
+  - path: /
+    rules:
+      except: sample.test
+  - path: /test
+    rules:
+      add: sample.test

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: querly
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Soutaro Matsumoto
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-27 00:00:00.000000000 Z
+date: 2017-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -180,9 +180,13 @@ files:
 - lib/querly/script.rb
 - lib/querly/script_enumerator.rb
 - lib/querly/version.rb
+- manual/configuration.md
+- manual/examples.md
+- manual/patterns.md
 - querly.gemspec
 - rules/sample.yml
 - sample.yaml
+- template.yml
 homepage: https://github.com/soutaro/querly
 licenses: []
 metadata: {}
@@ -202,7 +206,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: Pattern Based Checking Tool for Ruby