ruby_scope 0.1.1

data/README.markdown

@@ -0,0 +1,45 @@
+RubyScope
+---------
+Ruby colored binoculars for your code.
+
+    Usage: ruby_scope [options] path
+
+    Queries:
+            --def NAME                   Find the definition of instance method NAME
+            --class-def NAME             Find the definition of class method NAME
+            --call NAME                  Find method calls of NAME
+            --class NAME                 Find definition of NAME
+            --variable NAME              Find references to variable NAME
+            --assign NAME                Find assignments to NAME
+            --any NAME                   Find any reference to NAME (class, variable, number)
+            --custom SEXP_PATH           Searches for a custom SexpPath
+
+    Options:
+        -R                               Recursively search folders
+            --no-cache                   Do not use a cache
+            --cache PATH                 Use the cache at PATH (defaults to current dir)
+        -v, --verbose                    Verbose output
+        -h, --help                       Show this message
+        
+Find all the places `run` or `save` are called in your secret project:
+
+    ruby_scope -R --method 'run' --method 'save' ~/SecretProject
+    
+Where do I assign values to `a`:
+    
+    ruby_scope -R --assign 'a' ~/SecretProject
+    
+Of course regular expressions are fair game:
+
+    ruby_scope -R --def '/^test/' ~/SecretProject
+    
+Wicked hacker? Go crazy and write your own SexpPath queries:
+
+    ruby_scope --custom 's(:call, s(:ivar, atom), :save, _)'
+
+That finds all the saves on instance variables by the way.
+    
+Depends on RubyParser, SexpProcessor, and SexpPath, no gem yet.
+
+    Adam Sanderson
+    netghost@gmail.com

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  
+  Jeweler::Tasks.new do |s|
+    s.name = "ruby_scope"
+    s.summary = "Ruby colored binoluars for your code."
+    s.description = <<-DESC
+      A ruby hacker's search tool.  Quickly interrogate your code, seek out 
+      classes, methods, variable assignments, and more.
+    DESC
+    s.email = "netghost@gmail.com"
+    s.homepage = "http://github.com/adamsanderson/ruby_scope"
+    s.authors = ["Adam Sanderson"]
+    s.files = FileList["[A-Z]*", "{bin,lib,test}/**/*"]
+    
+    s.add_dependency 'sexp_processor',  '~> 3.0'
+    s.add_dependency 'ruby_parser',     '~> 2.0'
+    s.add_dependency 'sexp_path',       '>= 0.4'
+    
+    # Testing
+    s.test_files = FileList["test/**/*_test.rb"]
+    s.add_development_dependency 'mocha', '>= 0.9.8'
+  end
+
+rescue LoadError
+  puts "Jeweler not available. Install it for jeweler-related tasks with: sudo gem install jeweler"
+end
+
+Rake::RDocTask.new do |t|
+  #t.main = "README.rdoc"
+  t.rdoc_files.include("lib/**/*.rb")
+end
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = false
+end
+
+namespace :test do 
+  ['unit', 'integration'].each do |type|  
+    Rake::TestTask.new(type) do |t|
+      t.test_files = FileList["test/#{type}/**/*_test.rb"]
+      t.verbose = false
+    end
+  end
+end
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/bin/ruby_scope

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/ruby_scope'
+cli = RubyScope::CLI.new(ARGV)
+cli.run

data/lib/ruby_scope.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'ruby_parser'
+require 'sexp_path'
+require 'unified_ruby'
+require 'optparse'
+
+# RubyScope is a command line tool designed to help you scan ruby code lexically.
+# See the README for more information.
+module RubyScope
+end
+
+# Load RubyScope
+root = File.dirname(__FILE__)+'/ruby_scope/'
+%w[
+  scanner
+  sexp_cache
+  cli
+].each do |file|
+  require root+file
+end

data/lib/ruby_scope/cli.rb

@@ -0,0 +1,115 @@
+class RubyScope::CLI
+  attr_reader :paths
+  attr_reader :cache_path
+  attr_reader :scanner
+  
+  def initialize(args)
+    args = args.clone
+    @scanner = RubyScope::Scanner.new
+    @cache_path = FileUtils.pwd
+    
+    opts = OptionParser.new do |opts|    
+      opts.banner = "Usage: ruby_scope [options] queries path"
+
+      opts.separator ""
+      opts.separator "Queries:"
+
+      opts.on("--def NAME", "Find the definition of instance method NAME") do |name|
+        @scanner.add_query("s(:defn, #{v name}, _, _)")
+      end
+      
+      opts.on("--class-def NAME", "Find the definition of class method NAME") do |name|
+        @scanner.add_query("s(:defs, _, #{v name}, _, _)")
+      end
+      
+      opts.on("--call NAME", "Find method calls of NAME") do |name|
+        @scanner.add_query("s(:call, _, #{v name}, _)")
+      end
+      
+      opts.on("--class NAME", "Find definition of NAME") do |name|
+        @scanner.add_query("s(:class, #{v name}, _, _)")
+      end
+      
+      opts.on("--variable NAME", "Find references to variable NAME") do |name|
+        tag = instance_variable?(name) ? 'ivar' : 'lvar'
+        @scanner.add_query("s(:#{tag}, #{v name})")
+      end
+      
+      # Finds block arguments, variable assignments, method arguments (in that order)
+      opts.on("--assign NAME", "Find assignments to NAME") do |name|
+        tag = instance_variable?(name) ? 'iasgn' : 'lasgn'
+        @scanner.add_query("s(:#{tag}, #{v name}) | s(:#{tag}, #{v name}, _) | (t(:args) & SexpPath::Matcher::Block.new{|s| s[1..-1].any?{|a| a == #{v name}}} )")        
+      end
+      
+      opts.on("--any NAME", "Find any reference to NAME (class, variable, number)") do |name|
+        @scanner.add_query("include(#{v name})")
+      end
+      
+      opts.on("--custom SEXP_PATH", "Search for a custom SexpPath") do |sexp|
+        @scanner.add_query(sexp)
+      end
+      
+      opts.separator ""
+      opts.separator "Options:"
+      opts.on("-R", "Recursively search folders") do
+        @recurse = true
+      end
+      
+      opts.on("--no-cache", "Do not use a cache") do
+        @cache_path = nil
+      end
+      
+      opts.on("--cache PATH", "Use the cache at PATH (defaults to current dir)", "Beware, the cache can get rather large") do |path|
+        @cache_path = path if path
+      end
+      
+      opts.on("-v", "--verbose", "Verbose output") do
+        @scanner.verbose = true
+      end
+      
+      opts.on_tail("-h", "--help", "Show this message") do
+        puts opts
+        exit
+      end  
+    end
+    opts.parse!(args)
+    
+    @paths = args
+    
+    if @paths.empty?
+      puts opts
+      exit 1
+    end
+    
+    @paths = expand_paths(@paths) if @recurse
+    @scanner.cache = RubyScope::SexpCache.new(@cache_path) if @cache_path
+  end
+  
+  def run
+    @paths.each do |path|
+      @scanner.scan path
+    end
+  end
+  
+  protected
+  def expand_paths(paths)
+    paths.inject([]){|p,v| File.directory?(v) ? p.concat(Dir[File.join(v,'**/*.rb')]) : p << v; p }
+  end
+  
+  # Inserts the appropriate type of value given name.
+  # For instance:
+  #   v('/cake/') #=> /cake/ # regular expression match
+  #   v('apple')  #=> :apple # atom match
+  def v(name)
+    if name =~ /^\/.+\/$/ # regular expression matching regular expression... WIN!
+      "m(#{name})"
+    else
+      ":#{name}"
+    end
+  end
+  
+  def instance_variable?(name)
+    name[0..0] == '@'
+  end
+  
+end

data/lib/ruby_scope/scanner.rb

@@ -0,0 +1,92 @@
+class RubyScope::Scanner
+  attr_accessor :verbose
+  attr_accessor :cache
+  
+  def initialize
+    @query = nil
+    @verbose = false
+  end
+  
+  def add_query(pattern)
+    # Generate the pattern, we use a little instance_eval trickery here. 
+    sexp = case pattern
+      when String then SexpPath::SexpQueryBuilder.instance_eval(pattern)
+      when Sexp   then pattern
+      else raise ArgumentError, "Expected a String or Sexp"
+    end
+    
+    if @query 
+      @query = @query | sexp
+    else
+      @query = sexp
+    end
+    @query
+    
+  rescue Exception=>ex
+    puts "Invalid Pattern: '#{pattern}'"
+    puts "Trace:"
+    puts ex
+    puts ex.backtrace
+    exit 1    
+  end
+  
+  def query
+    @query.clone if @query
+  end
+  
+  def scan(path)
+    @path = path
+    begin
+      report_file path
+      
+      # Reset our cached code and split lines
+      @code,@lines = nil,nil
+            
+      # Load the code and parse it with RubyParser
+      # If we're caching pull from the cache, otherwise parse the code
+      sexp = @cache[path] if @cache
+      if !sexp
+        sexp = RubyParser.new.parse(code, @path)
+        @cache[path] = sexp if @cache
+      end
+ 
+      if sexp
+        # Search it with the given pattern, printing any results
+        sexp.search_each(@query) do |matching_sexp|
+          report_match matching_sexp
+        end 
+      end
+    rescue StandardError => ex
+      report_exception ex
+    end
+  end
+  
+  protected
+  def report_file(path)
+    puts @path if @verbose
+  end
+  
+  def report_match(match)
+    if !@lines
+      puts @path unless @verbose
+      @lines = code.split("\n")
+    end
+    line_number = match.sexp.line - 1
+    puts "%4i: %s" % [match.sexp.line, @lines[line_number].strip]
+  end
+  
+  def report_exception(ex)
+    debug "Problem processing '#{@path}'"
+    debug ex.message.strip
+    debug ex.backtrace.map{|line| "  #{line}"}.join("\n")
+  end
+  
+  def code
+    @code ||= File.read(@path)
+  end
+  
+  def debug(msg)
+    STDERR.print(msg.to_s.chomp + "\n")
+  end
+  
+end

data/lib/ruby_scope/sexp_cache.rb

@@ -0,0 +1,45 @@
+require 'dbm'
+class RubyScope::SexpCache
+  DB = DBM
+  CacheEntry = Struct.new(:last_modified, :sexp)
+  
+  def initialize(root)
+    @root = root
+  end
+  
+  def [] path
+    with_cache do |cache|
+      entry = cache[path]
+      entry = Marshal.load(entry) if entry
+      
+      if entry && entry.last_modified == last_modified(path)
+        entry.sexp
+      else
+        cache.delete path
+        nil
+      end
+    end
+  end
+  
+  def []= path,value
+    with_cache do |cache|
+      entry = CacheEntry.new(last_modified(path), value)
+      cache[path] = Marshal.dump(entry)
+    end
+  end
+  
+  def cache_path
+    @cache_path ||= File.join(@root,'.ruby_scope.cache')
+  end
+  
+  protected
+  def with_cache
+    DB.open(cache_path, 0666) do |cache|
+      yield cache
+    end
+  end
+  
+  def last_modified(path)
+    File.mtime(path)
+  end
+end

data/test/integration/console_test.rb

@@ -0,0 +1,51 @@
+require 'test/test_helper'
+
+# Self referential testing! 
+# These are awesome, absurd, and abusive. 
+# Make sure that the app actually does what we say it does.
+class ConsoleTest < Test::Unit::TestCase
+  ROOT = File.dirname(__FILE__) + '/../../'
+  
+  def test_finding_this_test
+    res = rs "--def '/^test/'"
+    assert_success
+    assert res['test_finding_this_test'], "Should have found this test"
+  end
+  
+  def test_finding_assignment
+    self_referential_line_number = __LINE__
+    
+    res = rs "--assign self_referential_line_number"
+    assert_success
+    assert res.split("\n").last =~ /(\d+)\:\s+self_referential_line_number = __LINE__/
+    assert_equal self_referential_line_number, $1.to_i
+  end
+  
+  def test_reading_the_help_and_making_queries
+    help = rs "--help"
+    assert help =~ /Queries:(.+)\s+Options:/m, "Should have a queries section"
+    queries = $1
+    queries.split("\n").each do |query|
+      next if query =~ /^\s*$/
+      assert query =~ /(--\S+)\s+(\S+)?/, "Each query should be a long flag with an optional parameter\n#{query.inspect}"
+      flag, param_type = $1,$2
+      param = case param_type
+        when 'NAME'       then  "a"
+        when 'SEXP_PATH'  then  "'s()'"
+        else                    nil
+      end
+      
+      res = rs "#{flag} #{param}"
+      assert_success res
+    end
+  end
+  
+  private
+  def rs(args)
+    `#{ROOT}bin/ruby_scope --no-cache #{args} #{__FILE__}`
+  end
+  
+  def assert_success(msg=nil)
+    assert $?.success?, msg||"Exited with status #{$?.exitstatus}"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/ruby_scope'
+
+require 'rubygems'
+require 'mocha'

data/test/unit/cli_test.rb

@@ -0,0 +1,41 @@
+require 'test/test_helper'
+
+class CLITest < Test::Unit::TestCase  
+  def test_configuring_scanner
+    query = scanner_with('--def','cats','.').query
+    assert query, "Should have generated a query"
+  end
+  
+  def test_configuring_scanner_with_regex
+    query = scanner_with('--def','/cats/','.').query
+    assert query, "Should have generated a query"
+  end
+  
+  def test_disabling_cache
+    c = cli_with('--no-cache', '.')
+    assert !c.cache_path
+    assert !c.scanner.cache
+  end
+  
+  def test_default_cache_behavior
+    c = cli_with('.')
+    assert c.cache_path
+    assert c.scanner.cache
+  end
+  
+  def test_custom_cache_path
+    path = File.dirname(__FILE__) + '../lib'
+    c = cli_with('--cache', path, '.')
+    assert_equal path, c.cache_path
+    assert c.scanner.cache
+  end
+  
+  private
+  def cli_with(*args)
+    RubyScope::CLI.new(args)
+  end
+  
+  def scanner_with(*args)
+    cli_with(*args).scanner
+  end
+end

data/test/unit/scanner_test.rb

@@ -0,0 +1,33 @@
+require 'test/test_helper'
+
+class ScannerTest < Test::Unit::TestCase
+  def setup
+    @scanner = RubyScope::Scanner.new
+    @scanner.cache = {}
+  end
+  
+  def test_scanning_cache_hit_with_no_match
+    path = 'cached_sample.rb'
+    @scanner.cache[path] = s(:a)
+    @scanner.add_query( s(:b) )
+
+    # Should have no hit
+    @scanner.expects(:report_match).never   
+    # Should not try to read the file since it is cached
+    @scanner.expects(:code).never           
+    
+    @scanner.scan(path)
+  end
+  
+  def test_scanning_cache_hit_with_match
+    path = 'cached_sample.rb'
+    @scanner.cache[path] = s(:a)
+    @scanner.add_query( s(:a) )
+
+    # Should report a match
+    @scanner.expects(:report_match)
+
+    @scanner.scan(path)
+  end
+  
+end

data/test/unit/sexp_cache_test.rb

@@ -0,0 +1,42 @@
+require 'test/test_helper'
+
+class SexpCacheTest < Test::Unit::TestCase
+  def setup
+    @path = File.dirname(__FILE__)
+    @cache = RubyScope::SexpCache.new(@path)
+    @cache.stubs(:last_modified).returns('ok')
+  end
+  
+  def teardown
+    File.delete(@cache.cache_path) if File.exists? @cache.cache_path
+  end
+  
+  def test_misses
+    assert_equal nil, @cache['missing']
+  end
+  
+  def test_writing_and_reading
+    key,value = 'a',s(:code)
+    
+    @cache[key] = value
+    assert_equal value, @cache[key]
+  end
+  
+  def test_expired_reads
+    key,value = 'a',s(:code)
+    
+    @cache[key] = value
+    # now invalidate the key
+    @cache.stubs(:last_modified).returns('old')
+    
+    assert_equal nil, @cache[key]
+  end
+  
+  def test_over_writing_and_reading
+    key,value1,value2 = 'a',s(:code),s(:new_code)
+
+    @cache[key] = value1
+    @cache[key] = value2
+    assert_equal value2, @cache[key]
+  end  
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: ruby_scope
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Adam Sanderson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-17 00:00:00 -07:00
+default_executable: ruby_scope
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: sexp_processor
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "3.0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: ruby_parser
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: sexp_path
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.4"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.8
+    version: 
+description: "      A ruby hacker's search tool.  Quickly interrogate your code, seek out \n      classes, methods, variable assignments, and more.\n"
+email: netghost@gmail.com
+executables: 
+- ruby_scope
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- README.markdown
+- Rakefile
+- VERSION
+- bin/ruby_scope
+- lib/ruby_scope.rb
+- lib/ruby_scope/cli.rb
+- lib/ruby_scope/scanner.rb
+- lib/ruby_scope/sexp_cache.rb
+- test/integration/console_test.rb
+- test/test_helper.rb
+- test/unit/cli_test.rb
+- test/unit/scanner_test.rb
+- test/unit/sexp_cache_test.rb
+has_rdoc: true
+homepage: http://github.com/adamsanderson/ruby_scope
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby colored binoluars for your code.
+test_files: 
+- test/integration/console_test.rb
+- test/unit/cli_test.rb
+- test/unit/scanner_test.rb
+- test/unit/sexp_cache_test.rb