├── .gitignore ├── .travis.yml ├── CODE_OF_CONDUCT.md ├── Gemfile ├── LICENSE.txt ├── README.md ├── Rakefile ├── bin ├── console └── setup ├── code_mapper.gemspec ├── lib ├── code_mapper.rb └── code_mapper │ ├── filter.rb │ ├── filter │ ├── callee.rb │ ├── max_depth.rb │ └── start_at.rb │ ├── output.rb │ ├── output │ ├── dot.rb │ └── text.rb │ ├── tracer.rb │ └── version.rb ├── sample-graph.png └── test ├── code_mapper_test.rb └── test_helper.rb /.gitignore: -------------------------------------------------------------------------------- 1 | /.bundle/ 2 | /.yardoc 3 | /Gemfile.lock 4 | /_yardoc/ 5 | /coverage/ 6 | /doc/ 7 | /pkg/ 8 | /spec/reports/ 9 | /tmp/ 10 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | language: ruby 3 | rvm: 4 | - 2.4.0 5 | before_install: gem install bundler -v 1.14.3 6 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at cmallette@gmail.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at [http://contributor-covenant.org/version/1/4][version] 72 | 73 | [homepage]: http://contributor-covenant.org 74 | [version]: http://contributor-covenant.org/version/1/4/ 75 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | # Specify your gem's dependencies in code_mapper.gemspec 4 | gemspec 5 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2017 Christian Joudrey 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # CodeMapper 2 | 3 | CodeMapper is a tool to generate call graphs from your Ruby code. 4 | 5 | I built this tool in order to familiarize myself with new Ruby codebases. You can read all about it [here](https://medium.com/@cjoudrey/familiarizing-myself-with-a-new-codebase-using-rubys-tracepoint-and-graphviz-aebd5d6ac2cd). 6 | 7 | ![](https://github.com/cjoudrey/code_mapper/raw/master/sample-graph.png) 8 | 9 | ## Installation 10 | 11 | Add this line to your application's Gemfile: 12 | 13 | ```ruby 14 | gem 'code_mapper' 15 | ``` 16 | 17 | And then execute: 18 | 19 | $ bundle 20 | 21 | Or install it yourself as: 22 | 23 | $ gem install code_mapper 24 | 25 | ## Usage 26 | 27 | Generating a call graph and outputting as text to STDOUT: 28 | 29 | ```ruby 30 | CodeMapper.trace do 31 | # Code to trace 32 | end 33 | ``` 34 | 35 | You can limit what classes and methods are outputted using `filter`: 36 | 37 | ```ruby 38 | CodeMapper.trace(filter: /^Dog\./) do 39 | Dog.new # will get outputted 40 | Cat.new # won't get outputted 41 | end 42 | ``` 43 | 44 | You can also limit the tracing to a specific lexical scope using `start_at`: 45 | 46 | ```ruby 47 | CodeMapper.trace(filter: /^Dog\./, start_at: 'Dog.bark') do 48 | dog = Dog.new # won't get outputted 49 | dog.bark # will get outputted and all Dog.* calls made within Dog.bark 50 | Dog.new # won't get outputted 51 | Cat.new # won't get outputted 52 | end 53 | ``` 54 | 55 | You can limit the depth of the call graph using `max_depth`: 56 | 57 | ```ruby 58 | CodeMapper.trace(max_depth: 3) do 59 | # Only first 3 levels will be outputted 60 | end 61 | ``` 62 | 63 | By default, the call graph will be outputted as text to `STDOUT`. 64 | 65 | However you can output the call graph to any `IO`: 66 | 67 | ```ruby 68 | CodeMapper.trace(output: CodeMapper::Output::Text.new($stderr)) do 69 | # Code to trace 70 | end 71 | ``` 72 | 73 | CodeMapper is also capable of outputting `dot` graphs which can be converted to an image using [`graphviz`](http://graphviz.org): 74 | 75 | ```ruby 76 | file = File.open('graph.dot', 'w') 77 | CodeMapper.trace(output: CodeMapper::Output::Dot.new(file)) do 78 | # Code to trace 79 | end 80 | file.close 81 | ``` 82 | 83 | ``` 84 | $ dot -Tpng graph.dot > graph.png 85 | ``` 86 | 87 | ## Contributing 88 | 89 | Bug reports and pull requests are welcome on GitHub at https://github.com/cjoudrey/code_mapper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. 90 | 91 | 92 | ## License 93 | 94 | The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). 95 | 96 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | require "bundler/gem_tasks" 2 | require "rake/testtask" 3 | 4 | Rake::TestTask.new(:test) do |t| 5 | t.libs << "test" 6 | t.libs << "lib" 7 | t.test_files = FileList['test/**/*_test.rb'] 8 | end 9 | 10 | task :default => :test 11 | -------------------------------------------------------------------------------- /bin/console: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | 3 | require "bundler/setup" 4 | require "code_mapper" 5 | 6 | # You can add fixtures and/or initialization code here to make experimenting 7 | # with your gem easier. You can also use a different console, if you like. 8 | 9 | # (If you use this, don't forget to add pry to your Gemfile!) 10 | # require "pry" 11 | # Pry.start 12 | 13 | require "irb" 14 | IRB.start(__FILE__) 15 | -------------------------------------------------------------------------------- /bin/setup: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | set -euo pipefail 3 | IFS=$'\n\t' 4 | set -vx 5 | 6 | bundle install 7 | 8 | # Do any other automated setup that you need to do here 9 | -------------------------------------------------------------------------------- /code_mapper.gemspec: -------------------------------------------------------------------------------- 1 | # coding: utf-8 2 | lib = File.expand_path('../lib', __FILE__) 3 | $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) 4 | require 'code_mapper/version' 5 | 6 | Gem::Specification.new do |spec| 7 | spec.name = "code_mapper" 8 | spec.version = CodeMapper::VERSION 9 | spec.authors = ["Christian Joudrey"] 10 | spec.email = ["cmallette@gmail.com"] 11 | 12 | spec.summary = %q{CodeMapper is a tool to generate call graphs from your Ruby code.} 13 | spec.homepage = "https://github.com/cjoudrey/code_mapper" 14 | spec.license = "MIT" 15 | 16 | spec.files = `git ls-files -z`.split("\x0").reject do |f| 17 | f.match(%r{^(test|spec|features)/}) 18 | end 19 | spec.bindir = "exe" 20 | spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) } 21 | spec.require_paths = ["lib"] 22 | 23 | spec.add_dependency "graphviz", "~> 0.4" 24 | 25 | spec.add_development_dependency "bundler", "~> 1.14" 26 | spec.add_development_dependency "rake", "~> 10.0" 27 | spec.add_development_dependency "minitest", "~> 5.0" 28 | end 29 | -------------------------------------------------------------------------------- /lib/code_mapper.rb: -------------------------------------------------------------------------------- 1 | require "code_mapper/version" 2 | require "code_mapper/tracer" 3 | require "code_mapper/filter/start_at" 4 | require "code_mapper/filter/callee" 5 | require "code_mapper/filter/max_depth" 6 | require "code_mapper/output/text" 7 | require "code_mapper/output/dot" 8 | 9 | module CodeMapper 10 | def self.trace(filter: nil, start_at: nil, max_depth: nil, output: CodeMapper::Output::Text.new($stdout), &block) 11 | filters = [] 12 | filters << Filter::Callee.new(filter) if filter 13 | filters << Filter::StartAt.new(start_at) if start_at 14 | filters << Filter::MaxDepth.new(max_depth) if max_depth 15 | 16 | tracer = Tracer.new(filters: filters, output: output) 17 | tracer.enable 18 | 19 | begin 20 | yield 21 | ensure 22 | tracer.disable 23 | end 24 | end 25 | end 26 | -------------------------------------------------------------------------------- /lib/code_mapper/filter.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | module Filter 3 | 4 | end 5 | end 6 | -------------------------------------------------------------------------------- /lib/code_mapper/filter/callee.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | module Filter 3 | class Callee 4 | def initialize(callee_matcher) 5 | @callee_matcher = callee_matcher 6 | end 7 | 8 | def keep?(tp, normalized_class_name) 9 | class_and_method = "#{normalized_class_name}.#{tp.method_id}" 10 | 11 | (@callee_matcher =~ class_and_method) != nil 12 | end 13 | end 14 | end 15 | end 16 | -------------------------------------------------------------------------------- /lib/code_mapper/filter/max_depth.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | module Filter 3 | class MaxDepth 4 | def initialize(max_depth) 5 | @max_depth = max_depth 6 | @depth = 0 7 | end 8 | 9 | def keep?(tp, _) 10 | if call_event?(tp) 11 | @depth += 1 12 | return false if @depth > @max_depth 13 | elsif return_event?(tp) 14 | old_depth = @depth 15 | @depth -= 1 16 | return false if old_depth > @max_depth 17 | end 18 | 19 | true 20 | end 21 | 22 | private 23 | 24 | def call_event?(tp) 25 | tp.event == :call || tp.event == :c_call 26 | end 27 | 28 | def return_event?(tp) 29 | tp.event == :return || tp.event == :c_return 30 | end 31 | end 32 | end 33 | end 34 | -------------------------------------------------------------------------------- /lib/code_mapper/filter/start_at.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | module Filter 3 | class StartAt 4 | def initialize(start_matcher) 5 | @start_matcher = start_matcher 6 | @started = false 7 | @stack = [] 8 | end 9 | 10 | def keep?(tp, normalized_class_name) 11 | class_and_method = "#{normalized_class_name}.#{tp.method_id}" 12 | 13 | if !@started && call_event?(tp) && matches?(class_and_method) 14 | @started = true 15 | end 16 | 17 | if @started && call_event?(tp) 18 | @stack << class_and_method 19 | return true 20 | end 21 | 22 | if @started && return_event?(tp) 23 | @stack.pop 24 | 25 | if @stack.empty? 26 | @started = false 27 | end 28 | end 29 | 30 | @started 31 | end 32 | 33 | private 34 | 35 | def call_event?(tp) 36 | tp.event == :call || tp.event == :c_call 37 | end 38 | 39 | def return_event?(tp) 40 | tp.event == :return || tp.event == :c_return 41 | end 42 | 43 | def matches?(class_and_method) 44 | case @start_matcher 45 | when Regexp 46 | (@start_matcher =~ class_and_method) != nil 47 | when String 48 | @start_matcher == class_and_method 49 | end 50 | end 51 | end 52 | end 53 | end 54 | -------------------------------------------------------------------------------- /lib/code_mapper/output.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | module Output 3 | end 4 | end 5 | -------------------------------------------------------------------------------- /lib/code_mapper/output/dot.rb: -------------------------------------------------------------------------------- 1 | require 'graphviz' 2 | 3 | module CodeMapper 4 | module Output 5 | class Dot 6 | def initialize(io) 7 | @io = io 8 | @stack = [] 9 | 10 | @graph = Graphviz::Graph.new('CodeMapper') 11 | @graph.attributes[:rankdir] = 'LR' 12 | end 13 | 14 | def push(tp, normalized_class_name) 15 | node = @graph.add_node("#{normalized_class_name}.#{tp.method_id.to_s}") 16 | node.attributes[:shape] = 'rectangle' 17 | 18 | if @stack != [] 19 | @stack.last.connect(node) 20 | end 21 | 22 | @stack << node 23 | end 24 | 25 | def pop(tp, normalized_class_name) 26 | @stack.pop 27 | end 28 | 29 | def done 30 | @io.puts @graph.to_dot 31 | end 32 | end 33 | end 34 | end 35 | -------------------------------------------------------------------------------- /lib/code_mapper/output/text.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | module Output 3 | class Text 4 | def initialize(io) 5 | @io = io 6 | @indent = '' 7 | end 8 | 9 | def push(tp, normalized_class_name) 10 | @io.puts "#{@indent}#{normalized_class_name}.#{tp.method_id.to_s}\n" 11 | @indent << ' ' 12 | end 13 | 14 | def pop(tp, normalized_class_name) 15 | @indent = @indent[0...-2] 16 | end 17 | 18 | def done 19 | end 20 | end 21 | end 22 | end 23 | -------------------------------------------------------------------------------- /lib/code_mapper/tracer.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | class Tracer 3 | def initialize(filters: [], output:) 4 | @filters = filters 5 | @output = output 6 | end 7 | 8 | def enable 9 | tracer.enable 10 | end 11 | 12 | def disable 13 | tracer.disable 14 | @output.done 15 | end 16 | 17 | private 18 | 19 | def tracer 20 | indent = '' 21 | 22 | @tracer ||= TracePoint.new(:call, :c_call, :return, :c_return) do |tp| 23 | normalized_class_name = tp.defined_class.to_s 24 | .sub(/\#/, '\1') 25 | .sub(/\#<(.*)\:0x[0-f]+\>/, '\1') 26 | 27 | next if @filters.any?{ |filter| !filter.keep?(tp, normalized_class_name) } 28 | 29 | if tp.event == :call || tp.event == :c_call 30 | @output.push(tp, normalized_class_name) 31 | elsif tp.event == :return || tp.event == :c_return 32 | @output.pop(tp, normalized_class_name) 33 | end 34 | end 35 | end 36 | end 37 | end 38 | -------------------------------------------------------------------------------- /lib/code_mapper/version.rb: -------------------------------------------------------------------------------- 1 | module CodeMapper 2 | VERSION = "0.1.0" 3 | end 4 | -------------------------------------------------------------------------------- /sample-graph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cjoudrey/code_mapper/f3088c1ab90b54f0197355fb98f6a0740b0935ab/sample-graph.png -------------------------------------------------------------------------------- /test/code_mapper_test.rb: -------------------------------------------------------------------------------- 1 | require 'test_helper' 2 | 3 | class CodeMapperTest < Minitest::Test 4 | def test_that_it_has_a_version_number 5 | refute_nil ::CodeMapper::VERSION 6 | end 7 | 8 | def test_it_does_something_useful 9 | assert false 10 | end 11 | end 12 | -------------------------------------------------------------------------------- /test/test_helper.rb: -------------------------------------------------------------------------------- 1 | $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__) 2 | require 'code_mapper' 3 | 4 | require 'minitest/autorun' 5 | --------------------------------------------------------------------------------