private_please 0.0.2 → 0.0.3

data/lib/private_please.rb

@@ -1,83 +1,66 @@
 require 'private_please/version'
-require 'private_please/configuration'
-require 'private_please/candidates'
-require 'private_please/recorder'
-require 'private_please/report'
-require 'private_please/line_change_tracker'
+require 'private_please/ruby_backports'
+require 'private_please/candidate'
+require 'private_please/storage/calls_store'
+require 'private_please/storage/candidates_store'
+require 'private_please/storage/methods_names'
+require 'private_please/storage/methods_names_bucket'
+require 'private_please/report/reporter'
+require 'private_please/tracking/line_change_tracker'
+require 'private_please/tracking/extension'
+require 'private_please/tracking/instrumentor'
+require 'private_please/tracking/instruments_all_below'
 
 module PrivatePlease
 
-  def private_please(*args)
-    klass = self
-    args.reject!{|m| !klass.instance_methods.include?(m.to_s)}
-    storage.candidates[klass.to_s] += args
-    args.each do |m|
-      mark_method(m)
-    end
+  def self.install
+    Module.send :include, PrivatePlease::Tracking::Extension
   end
 
 #--------------
 # config
 #--------------
-  def activate(flag)
-    config.activate(flag)
+
+  def self.after_method_call(candidate, outside_call)
+    outside_call ?
+      calls_store.store_outside_call(candidate) :
+      calls_store.store_inside_call(candidate)
   end
 
-  def active?
-    !!config.active
+  def self.remember_candidate(candidate)
+    candidates_store.store(candidate)
   end
 
+
 #--------------
-# partners :
+# data & config containers :
 #--------------
-  def recorder ; Recorder     .instance end
-  def storage  ; Candidates   .instance end
-  def config   ; Configuration.instance end
 
   def self.reset_before_new_test
-    Recorder      .reset_before_new_test
-    Candidates    .reset_before_new_test
-    Configuration .reset_before_new_test
+    @@_calls_store = @@_candidates_store = nil
   end
 
 #--------------
 # report
 #--------------
-  def report
-    Report.build(storage)
+
+  def self.report
+    Report::Reporter.new(candidates_store, calls_store)
   end
 
 private
 
-  def mark_method(name)
-    self_class = self.class
-    PrivatePlease.recorder.record_candidate(self_class, name)
-    orig_method = instance_method(name)
-    define_method(name) do |*args, &blk|
-      set_trace_func(nil) #don't track activity while here
-
-      self_class = self.class
-      if PrivatePlease.active?
-        call_initiator = LineChangeTracker.prev_self
-        is_outside_call = call_initiator.class != self_class
-        is_outside_call ?
-          PrivatePlease.recorder.record_outside_call(self_class, name) :
-          PrivatePlease.recorder.record_inside_call( self_class, name)
-      end
-
-      # make the call :
-      set_trace_func(LineChangeTracker::MY_TRACE_FUN)
-      orig_method.bind(self).call(*args, &blk)
-    end
+  def self.calls_store
+  @@_calls_store ||= Storage::CallsStore.new
   end
 
+  def self.candidates_store
+    @@_candidates_store ||= Storage::CandidatesStore.new
+  end
 end
 
-Module.send :include, PrivatePlease
 
+PrivatePlease.install
 at_exit {
-  if PrivatePlease.active?
-    puts '-'*888
-    puts PrivatePlease.report.to_s
-  end
+  puts PrivatePlease.report.to_s
 }

data/private_please.gemspec

@@ -18,4 +18,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rake' # to run 'All specs' in Rubymine
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'rb-fsevent'
 end

data/sample.rb

@@ -0,0 +1,68 @@
+#   require 'private_please'
+require 'lib/private_please'  # use the latest version
+
+module ReportSample
+                                                ###########################################
+  class Simple                                  # Internal calls :                        #
+                                                # -> called methods are _GOOD CANDIDATES_ #
+    def make_internal_calls                     ###########################################
+      instance_m_1                              #  i -> i
+      instance_m_3                              #  i -> i
+      self.class.class_m_1                      #  i -> C
+      self.class.class_m_2                      #  i -> C
+      self.class.c_make_internal_method_calls   #  i -> C --> C
+    end                                         #         +-> i
+
+    def self.c_make_internal_method_calls       #
+      class_m_1                                 #  C -> C
+      new.instance_m_2                          #  C -> i
+    end                                         #
+  end
+
+                                                #######################################################
+  class AnotherClass                            # External calls (would fail if methods were private) #
+    private_please                              # -> called methods are _BAD CANDIDATES_              #
+    def make_external_calls                     #######################################################
+      Simple.new.instance_m_1                   #  i -> i
+      Simple    .class_m_1                      #  i -> C
+      self.class.c_make_external_calls          #  i -> C -> i
+    end                                         #         -> C
+    def self.c_make_external_calls              #
+      Simple.new.instance_m_1                   #  C -> i
+      Simple    .class_m_1                      #  C -> C
+      Simple    .class_m_2                      #  C -> C
+    end                                         #
+    def call_the_candidate_from_inside_and_outside
+      make_external_calls
+      Simple.new.make_internal_calls
+    end
+    def never_called; end
+    def self.never_called_c; end
+  end
+
+#-----------------------------------------------------------------------------------------------------------------------
+ class Simple
+    def self.not_a_candidate_c1;
+      class_m_2
+    end
+
+    private_please
+    def instance_m_1;   end
+    def instance_m_2;   end
+    def instance_m_3;   end
+
+    def self.class_m_1;
+      class_m_2
+    end
+    def self.class_m_2; end
+
+    def never_called_1;             end
+    def self.class_never_called_1;  end
+  end
+end unless defined?(ReportSample::Simple)
+#-----------------------------------------------------------------------------------------------------------------------
+
+ReportSample::Simple.new.make_internal_calls
+ReportSample::AnotherClass.new.make_external_calls
+ReportSample::AnotherClass.c_make_external_calls
+

data/spec/01_marking_candidate_methods_to_observe_spec.rb

@@ -0,0 +1,153 @@
+require 'spec_helper'
+
+describe PrivatePlease, 'collecting the details of candidate-methods to observe' do
+  module MarkingTest; end
+
+  let(:candidates_store) { PrivatePlease.storage }
+
+# ----------------
+  context 'observing with `private_please(<method names>)`' do
+# ----------------
+
+    it('stores the instance methods names in the candidates list, indexed by their owning class') do
+      class MarkingTest::Simple1
+        def foo ; 'foo' end
+        def bar ; 'bar' end
+        def buz ; 'bar' end
+        private_please  :bar, 'buz'    # <<-- what we test
+      end
+
+      assert_instance_methods_candidates 'MarkingTest::Simple1' =>[:bar, :buz]
+    end
+
+
+    it('does not work with class methods') do
+      class MarkingTest::Simple1b
+        def self.found ; 'I am a class method' end
+        private_please  :found    # <<-- class method => not observed
+      end
+
+      assert_instance_methods_candidates ({})
+      assert_class_methods_candidates    ({})
+    end
+
+    it('ignores invalid candidates (method not found in the class)') do
+      class MarkingTest::Simple2
+        def found ; 'foo' end
+        private_please  :found             # <<-- valid
+        private_please  :not_found_method  # <<-- not found => INvalid
+      end
+
+      assert_instance_methods_candidates 'MarkingTest::Simple2' =>[:found]
+    end
+
+    it('ignores duplicates') do
+      class MarkingTest::Simple3
+        def found ; 'foo' end
+        private_please  :found             #
+        private_please  :found             # duplicate -> ignore
+      end
+
+      assert_instance_methods_candidates 'MarkingTest::Simple3' =>[:found]
+    end
+  end
+
+
+# ----------------
+  context 'observing with `private_please()`' do
+# ----------------
+
+    example 'all the instance methods defined after `private_please` are stored as candidates' do
+
+      class MarkingTest::Automatic1
+        def foo ; end          #    NO (too early)
+      private_please # --->    # <start observing>
+        def baz ; end          #    *
+      public                   #    *
+        def qux ; end          #    *
+        def included ; end     #    * special name, but valid candidate (in classes).
+      end
+      assert_instance_methods_candidates 'MarkingTest::Automatic1' =>[:baz, :qux, :included]
+      assert_class_methods_candidates    ({})
+    end
+
+
+    example 'all the class methods defined after `private_please` are stored as candidates' do
+      class MarkingTest::Automatic1b
+        def self.foo ; end       #    NO (too early)
+      private_please   # --->    # <start observing>
+        def self.baz ; end       #    YES
+      public                     #    *
+        def self.qux ; end       #    YES
+        def self.included ; end  #    * special name, but valid candidate (in classes).
+      end
+
+      assert_instance_methods_candidates ({})
+      assert_class_methods_candidates    'MarkingTest::Automatic1b' =>[:baz, :qux, :included]
+    end
+
+    example ('already private methods are ignored/not observed') do
+      class MarkingTest::Automatic1c
+      private_please   # --->    # <start observing>
+        def self.baz ; end       #    YES
+      public                     #    *
+        def qux ; end            #    YES
+      private                    #
+        def already_private ; end            #    NO
+        class << self
+        private
+          def class_already_private ; end     #    NO
+        end
+      end
+
+      assert_instance_methods_candidates 'MarkingTest::Automatic1c' =>[:qux]
+      assert_class_methods_candidates    'MarkingTest::Automatic1c' =>[:baz]
+    end
+
+
+    example 'method coming from an included module are observed too' do
+#TODO : find a better way to instrument modules
+#TODO : find a way to instrument modules automatically (? possible)
+
+      module Extra002               ; private_please end  # <<=== Pre-instrument.
+      module Extra002::ClassMethods ; private_please end  # <<=== Pre-instrument.
+
+      module Extra002                                     # Reopen the pre-instrumented
+        def im_from_module ; end                          # module.
+        def self.included(base)                           #
+          base.extend ClassMethods                        #
+        end                                               #
+        module ClassMethods                               #
+          def cm_from_modulex ; end                        #
+        end                                               #
+      end                                                 #
+      assert_instance_methods_candidates 'Extra002'                 =>[:im_from_module],
+                                         'Extra002::ClassMethods'   =>[:cm_from_module]
+      assert_class_methods_candidates    ({})
+    end
+  end
+
+
+# ----------------
+  context 'observing with `include PrivatePlease::Tracking::InstrumentsAllBelow`' do
+# ----------------
+
+    example 'all the methods defined subsequently are stored as candidates' do
+
+      class MarkingTest::Automatic2
+        def foo ; end
+        def bar ; end
+        include PrivatePlease::Tracking::InstrumentsAllBelow # ---> # <start observing>
+        def baz ; end                          #    YES
+        def self.class_m1; end                 #    YES
+      protected                                #
+        def qux ; end                          #    YES
+      end
+
+      assert_instance_methods_candidates 'MarkingTest::Automatic2' =>[:baz, :qux]
+      assert_class_methods_candidates    'MarkingTest::Automatic2' =>[:class_m1]
+    end
+
+  end
+
+end

data/spec/02_logging_calls_on_candidate_methods_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe PrivatePlease, 'calling observed methods and logging calls in 2 categories : internal or external' do
+
+  before do
+#-----------------------------------------------------------------------------------------------------------------------
+    require File.dirname(__FILE__) + '/fixtures/sample_class_with_all_calls_combinations'
+#-----------------------------------------------------------------------------------------------------------------------
+  end
+
+
+  NO_CALLS_OBSERVED = {}
+
+  example ('pure internal calls are categorized correctly') do
+    CallsSample::Simple.new.make_internal_calls
+    assert_calls_detected :inside     => {'CallsSample::Simple' => mnames_for([:instance_m_1, :instance_m_2])},
+                          :outside    => NO_CALLS_OBSERVED,
+                          :inside_c   => {'CallsSample::Simple' => mnames_for([:class_m_1, :class_m_2])},
+                          :outside_c  => NO_CALLS_OBSERVED
+  end
+
+  example ('pure external calls are categorized correctly') do
+    CallsSample::AnotherClass.new.make_external_calls
+    assert_calls_detected :inside     => NO_CALLS_OBSERVED,
+                          :outside    => {'CallsSample::Simple' => mnames_for([:instance_m_1])},
+                          :inside_c   => {'CallsSample::Simple' => mnames_for([:class_m_2])},
+                          :outside_c  => {'CallsSample::Simple' => mnames_for([:class_m_1])}
+  end
+
+  example('when a method is called both from inside and from outside its class, it is recorded is both categories') do
+    CallsSample::AnotherClass.new.call_the_candidate_from_inside_and_outside
+    assert_calls_detected :inside     => {'CallsSample::Simple' => mnames_for([:instance_m_1, :instance_m_2])},
+                          :outside    => {'CallsSample::Simple' => mnames_for([:instance_m_1])},
+                          :inside_c   => {'CallsSample::Simple' => mnames_for([:class_m_2, :class_m_1])},
+                          :outside_c  => {'CallsSample::Simple' => mnames_for([:class_m_1])}
+  end
+
+#-----------------------------------------------------------------------------------------------------------------------
+end

data/spec/04_instrumented_program_activity_observation_result_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+describe 'PrivatePlease.report', 'observing an instrumented program activity' do
+
+  def run_the_instrumented_program
+    ActivityTest::Simple.new.tap do |o|
+      o.not_a_candidate_1
+      o.not_a_candidate_2
+      o.class.not_a_candidate_c1
+      o.bad_candidate_3
+      o.bad_candidate_6
+      o.class.bad_candidate_c3
+    end
+    ActivityTest::Simple2.new.bad_candidate_too
+    ActivityTest::Simple2    .bad_candidate_c_too
+  end
+
+  before do
+
+    module ActivityTest
+      class Simple
+        def not_a_candidate_1;    bad_candidate_3   end
+        def not_a_candidate_2;    good_candidate_7  end
+        def self.not_a_candidate_c1;
+          good_candidate_c2
+        end
+      private_please
+        def bad_candidate_3;      good_candidate_4  end
+        def good_candidate_4;     good_candidate_5  end
+        def good_candidate_5;     bad_candidate_6   end
+        def bad_candidate_6;      good_candidate_7  end
+        def good_candidate_7;                       end
+        def ignored_8  ;          'never called'    end
+        def self.ignored_c9 ;          'never called'    end
+        def self.good_candidate_c2;                 end
+        def self.bad_candidate_c3;                  end
+      end
+
+      class Simple2
+      private_please
+        def bad_candidate_too;                      end
+        def ignored_2;            'never called'    end
+        def self.ignored_c3;      'never called'    end
+        def self.bad_candidate_c_too;               end
+      end
+    end unless defined?(ActivityTest::Simple)
+  end
+
+  # Note: test all in 1 go because testing in bits would fail, and it differs from real usage.
+  it 'obtains the right info by observing the program activity' do
+    run_the_instrumented_program
+    the_report = PrivatePlease.report
+    {
+        :good_candidates  => the_report.good_candidates,
+        :good_candidates_c => the_report.good_candidates_c,
+        :bad_candidates   => the_report.bad_candidates,
+        :bad_candidates_c => the_report.bad_candidates_c,
+        :ignored          => the_report.never_called_candidates,
+        :ignored_c        => the_report.never_called_candidates_c
+    }.should == {
+        :good_candidates  => {
+            'ActivityTest::Simple'   =>  mnames_for([:good_candidate_4, :good_candidate_5, :good_candidate_7])
+        },
+        :good_candidates_c => {
+            'ActivityTest::Simple'   =>  mnames_for([:good_candidate_c2])
+        },
+        :bad_candidates   => {
+            'ActivityTest::Simple'   =>  mnames_for([:bad_candidate_3, :bad_candidate_6]),
+            'ActivityTest::Simple2'  =>  mnames_for([:bad_candidate_too])
+        },
+        :bad_candidates_c => {
+            'ActivityTest::Simple'   =>  mnames_for([:bad_candidate_c3]),
+            'ActivityTest::Simple2'  =>  mnames_for([:bad_candidate_c_too])
+        },
+        :ignored          => {
+            'ActivityTest::Simple'   =>  mnames_for([:ignored_8]),
+            'ActivityTest::Simple2'  =>  mnames_for([:ignored_2])
+        },
+        :ignored_c        => {
+            'ActivityTest::Simple'   =>  mnames_for([:ignored_c9]),
+            'ActivityTest::Simple2'  =>  mnames_for([:ignored_c3])
+        }
+    }
+    puts the_report.to_s
+    puts "\n***report building time : #{the_report.building_time} sec."
+
+  end
+
+end

data/spec/fixtures/sample_class_for_report.rb

@@ -0,0 +1,54 @@
+module ReportSample
+                                                ###########################################
+  class Simple                                  # Internal calls :                        #
+                                                # -> called methods are _GOOD CANDIDATES_ #
+    def make_internal_calls                     ###########################################
+      instance_m_1                              #  i -> i
+      self.class.class_m_1                      #  i -> C
+      self.class.c_make_internal_method_calls   #  i -> C --> C
+    end                                         #         +-> i
+
+    def self.c_make_internal_method_calls       #
+      class_m_1                                 #  C -> C
+      new.instance_m_2                          #  C -> i
+    end                                         #
+  end
+
+                                                #######################################################
+  class AnotherClass                            # External calls (would fail if methods were private) #
+                                                # -> called methods are _BAD CANDIDATES_              #
+    def make_external_calls                     #######################################################
+      Simple.new.instance_m_1                   #  i -> i
+      Simple    .class_m_1                      #  i -> C
+      self.class.c_make_external_calls          #  i -> C -> i
+    end                                         #         -> C
+    def self.c_make_external_calls              #
+      Simple.new.instance_m_1                   #  C -> i
+      Simple    .class_m_1                      #  C -> C
+    end                                         #
+    def call_the_candidate_from_inside_and_outside
+      make_external_calls
+      Simple.new.make_internal_calls
+    end
+  end
+
+#-----------------------------------------------------------------------------------------------------------------------
+ class Simple
+    def self.not_a_candidate_c1;
+      class_m_2
+    end
+
+  private_please
+    def instance_m_1;   end
+    def instance_m_2;   end
+
+    def self.class_m_1;
+      class_m_2
+    end
+    def self.class_m_2; end
+
+    def never_called_1;             end
+    def self.class_never_called_1;  end
+  end
+end unless defined?(ReportSample::Simple)
+#-----------------------------------------------------------------------------------------------------------------------

data/spec/fixtures/sample_class_with_all_calls_combinations.rb

@@ -0,0 +1,69 @@
+module CallsSample
+                                                ###########################################
+  class Simple                                  # Internal calls :                        #
+                                                # -> called methods are _GOOD CANDIDATES_ #
+    def make_internal_calls                     ###########################################
+      instance_m_1                              #  i -> i
+      self.class.class_m_1                      #  i -> C
+      self.class.c_make_internal_method_calls   #  i -> C --> C
+    end                                         #         +-> i
+
+    def self.c_make_internal_method_calls       #
+      class_m_1                                 #  C -> C
+      new.instance_m_2                          #  C -> i
+    end                                         #
+  end
+
+                                                #######################################################
+  class AnotherClass                            # External calls (would fail if methods were private) #
+                                                # -> called methods are _BAD CANDIDATES_              #
+    def make_external_calls                     #######################################################
+      Simple.new.instance_m_1                   #  i -> i
+      Simple    .class_m_1                      #  i -> C
+      self.class.c_make_external_calls          #  i -> C -> i
+    end                                         #         -> C
+    def self.c_make_external_calls              #
+      Simple.new.instance_m_1                   #  C -> i
+      Simple    .class_m_1                      #  C -> C
+    end                                         #
+    def call_the_candidate_from_inside_and_outside
+      make_external_calls
+      CallsSample::Simple.new.make_internal_calls
+    end
+  end
+
+#-----------------------------------------------------------------------------------------------------------------------
+  module Extra               ; private_please end  # <<=== Pre-instrument.
+  module Extra::ClassMethods ; private_please end  # <<=== Pre-instrument.
+
+  module Extra
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    def an_instance_method ; end
+    module ClassMethods
+      def a_class_method_via_module_Extra ; end
+    end
+  end
+
+
+  class Simple
+    def self.not_a_candidate_c1;
+      class_m_2
+    end
+
+  private_please
+    include Extra
+    def instance_m_1;   end
+    def instance_m_2;   end
+
+    def self.class_m_1;
+      class_m_2
+    end
+    def self.class_m_2; end
+
+    def never_called_1;             end
+    def self.class_never_called_1;  end
+  end
+#-----------------------------------------------------------------------------------------------------------------------
+end unless defined?(CallsSample::Simple)

data/spec/spec_helper.rb

@@ -1,9 +1,60 @@
-# This file was generated by the `rspec --init` command. Conventionally, all
+# This file was (originally) generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
 # Require this file using `require "spec_helper"` to ensure that it is only
 # loaded once.
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+module PrivatePlease
+  def self.reset_before_new_test
+    PrivatePlease .reset_before_new_test
+  end
+end
+
+class Hash
+  def to_methods_names_bucket
+    PrivatePlease::Storage::MethodsNamesBucket.new.tap do |bucket|
+      each_pair do |class_name, method_names_as_a|
+        method_names_as_a.each do |method_name|
+          bucket.add_method_name(class_name, method_name)
+        end
+      end
+    end
+  end
+end
+
+def assert_instance_methods_candidates(raw_expected)
+  expected = raw_expected.to_methods_names_bucket if raw_expected.is_a?(Hash)
+  PrivatePlease.candidates_store.instance_methods.should == expected
+end
+
+def assert_class_methods_candidates(raw_expected)
+  expected = raw_expected.to_methods_names_bucket if raw_expected.is_a?(Hash)
+  PrivatePlease.candidates_store.class_methods.should == expected
+end
+
+
+
+def assert_calls_detected(expected)
+  calls_db = PrivatePlease.calls_store
+  { :inside    => calls_db.internal_calls,
+    :inside_c  => calls_db.class_internal_calls,
+    :outside   => calls_db.external_calls,
+    :outside_c => calls_db.class_external_calls
+  }.should == expected
+end
+
+NO_CALLS_OBSERVED = {}
+
+def assert_no_calls_detected
+  assert_calls_detected :inside   => NO_CALLS_OBSERVED, :outside   => NO_CALLS_OBSERVED,
+                        :inside_c => NO_CALLS_OBSERVED, :outside_c => NO_CALLS_OBSERVED
+end
+
+def mnames_for(args)
+  PrivatePlease::Storage::MethodsNames.new(Array(args))
+end
+
 RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true
   config.run_all_when_everything_filtered = true

data/spec/units/calls_store_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+
+describe PrivatePlease::Storage::CallsStore do
+
+  let(:calls_store     )  { PrivatePlease::Storage::CallsStore.new }
+
+  context 'when fresh' do
+    it 'is empty (has no calls)' do
+      calls_store.internal_calls       .should be_empty
+      calls_store.external_calls       .should be_empty
+    end
+  end
+
+end