cordon 0.2.2 → 0.3.0

data/README.markdown

@@ -11,7 +11,7 @@ From Wikipedia:
 
 I've never been a big fan of the way RSpec adds <code>#should</code> and <code>#should_not</code> to Kernel, but until recently I'd never been able to articulate why.  Then I worked on a project that became <a href="https://github.com/geeksam/kookaburra/">Kookaburra</a>, and I found a specific reason to be annoyed.
 
-Basically, putting <code>#should</code> on all objects gives you the freedom to <s>shoot yourself in the foot</s> put RSpec expectations *anywhere*, not just inside an <code>#it</code> block.  So, I went looking for a way to make <code>#should</code> explode if it was called outside a specific context.
+Basically, putting <code>#should</code> on all objects gives you the freedom to <strike>shoot yourself in the foot</strike>^H^H^H put RSpec expectations *anywhere*, not just inside an <code>#it</code> block.  So, I went looking for a way to make <code>#should</code> explode if it was called outside a specific context.
 
 After several false starts and horrible ideas, I've got something that actually isn't too bad.
 
@@ -44,13 +44,23 @@ In both examples, note that Cordon's <code>.embargo</code> method must be called
 
 ## TODO
 
-- Write integration macros (and tests, obviously) for various spec frameworks:
-  - <s>RSpec</s>
-  - <s>MiniTest::Spec</s>
-  - <s>Yoda</s> <em>(Actually, Yoda appears to abuse Ruby syntax badly enough that it may not work with Cordon.)</em>
-  - ?
-- <s>Add a declarative API to customize the name of the function that wraps assertions</s>
-- probably some other stuff I can't think of at the moment
+<!-- Apparently Markdown and HTML don't mix, because "* <strike>foo</strike>" doesn't work the way I thought it should -->
+<ul>
+  <li>
+    Write integration macros (and tests, obviously) for various spec frameworks:
+    <ul>
+      <li><strike>RSpec</strike></li>
+      <li><strike>MiniTest::Spec</strike></li>
+      <li><strike>Yoda</strike> <em>(Actually, Yoda appears to abuse Ruby syntax badly enough that it may not work with Cordon.)</em></li>
+      <li>?</li>
+    </ul>
+  </li>
+  <li><strike>Add a declarative API to customize the name of the function that wraps assertions</strike></li>
+  <li>RDoc</li>
+  <li>Add a "detection mode" which rescues Cordon::Violation, records the backtrace, and reports all violations in a Kernel#at_exit callback. (UPDATE:  added Cordon.monitor for frameworks, and Cordon.watchlist for methods, but didn't get #at_exit working yet.)</li>
+  <li>MAYBE: Figure out how to raise Cordon::Violation only when in (or not in?) a certain calling context (this could be hairy), which might make #assert_that optional</li>
+  <li>probably some other stuff I can't think of at the moment</li>
+</ul>
 
 
 
@@ -68,5 +78,4 @@ In both examples, note that Cordon's <code>.embargo</code> method must be called
 
 ## Copyright
 
-Copyright (c) 2012 Sam Livingston-Gray. See LICENSE.txt for
-further details.
+Copyright (c) 2012 Sam Livingston-Gray. See LICENSE.txt for further details.

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.3.0

data/cordon.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{cordon}
-  s.version = "0.2.2"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Sam Livingston-Gray}]
-  s.date = %q{2012-03-09}
+  s.date = %q{2012-03-15}
   s.description = %q{A bit of an experiment, really}
   s.email = %q{geeksam@gmail.com}
   s.extra_rdoc_files = [
@@ -24,18 +24,21 @@ Gem::Specification.new do |s|
     "cordon.gemspec",
     "lib/cordon.rb",
     "lib/cordon/blacklist.rb",
+    "lib/cordon/method_list.rb",
     "lib/cordon/sanitaire.rb",
     "lib/cordon/violation.rb",
+    "lib/cordon/watchlist.rb",
     "lib/cordon/whitelist.rb",
     "test/framework_integration/minitest_spec_spec.rb",
     "test/framework_integration/rspec_spec.rb",
     "test/helper.rb",
     "test/integration/backtrace_cleaning_test.rb",
-    "test/integration/cordon_basic_examples_test.rb",
-    "test/integration/cordon_customization_test.rb",
-    "test/integration/cordon_default_behavior_test.rb",
-    "test/integration/cordon_edge_cases_test.rb",
-    "test/integration/integration_test_helper.rb"
+    "test/integration/basic_examples_test.rb",
+    "test/integration/customization_test.rb",
+    "test/integration/default_behavior_test.rb",
+    "test/integration/edge_cases_test.rb",
+    "test/integration/integration_test_helper.rb",
+    "test/integration/watchlist_test.rb"
   ]
   s.homepage = %q{http://github.com/geeksam/cordon}
   s.licenses = [%q{WTFPL}]

data/lib/cordon.rb

@@ -26,27 +26,78 @@ end
 
 
 module Cordon
-  # Declare specific methods as off-limits
+  # Shorthand for blacklisting the undesirable methods in specific frameworks
+  def self.embargo(framework)
+    wrap_framework(framework, :blacklist)
+  end
+
+  # Shorthand for watchlisting the undesirable methods in specific frameworks
+  # NOTE:  while this will record incursions, you'll have to call Cordon.incursion_report
+  # yourself until I figure out how to make it print out at exit.
+  def self.monitor(framework)
+    wrap_framework(framework, :watchlist)
+  end
+
+  # Declare specific methods as off-limits so that invocations raise an exception
   def self.blacklist(subject, methods)
-    methods.each do |method|
-      Blacklist.blacklist_method(subject, method.to_sym)
-    end
+    Blacklist.wrap_methods(subject, methods)
   end
 
-  # Shorthand for blacklisting the undesirable methods in specific frameworks
-  def self.embargo(framework)
+  # Declare specific methods as off-limits so that invocations are logged
+  def self.watchlist(subject, methods)
+    Watchlist.wrap_methods(subject, methods)
+  end
+
+  # Allow user-defined aliases of #assert_that
+  def self.wrap_assertions_with(custom_method_name)
+    Sanitaire.wrap_assertions_with(custom_method_name)
+  end
+
+  # Convenience accessor for reporting on watchlist incursions
+  def self.incursions
+    Watchlist.incursions
+  end
+
+  # Plain-text report of watchlist incursions
+  def self.incursion_report
+    Watchlist.incursion_report
+  end
+
+  # Allow custom filtering of backtraces on Cordon::Violation errors.
+  # Pass this a block that takes a backtrace and returns a backtrace.
+  # Multiple filters can be defined; all will be applied.
+  def self.filter_violation_backtrace(&proc)
+    Violation.add_custom_backtrace_filter(&proc)
+  end
+
+  # Reset custom filtering of backtraces.
+  # (This is mostly here for ease of testing.)
+  def self.dont_filter_violation_backtrace!
+    Violation.clear_custom_backtrace_filters
+  end
+
+protected
+
+  def self.wrap_framework(framework, technique)
+    raise "Don't know how to wrap framework with #{technique.inspect}!" unless [:blacklist, :watchlist].include?(technique)
+
+    # Figure out which methods to wrap
+    list = []
     case framework
     when :rspec
-      blacklist Kernel, [:should, :should_not]
+      list << [Kernel, [:should, :should_not]]
     when :minitest_spec
       must_and_wont = MiniTest::Expectations.instance_methods.map(&:to_s).select {|e| e =~ /^(must|wont)_/}
-      blacklist MiniTest::Expectations, must_and_wont
+      list << [MiniTest::Expectations, must_and_wont]
     else
       raise "I don't know how to embargo #{framework}!"
     end
-  end
 
-  def self.wrap_assertions_with(custom_method_name)
-    Sanitaire.wrap_assertions_with(custom_method_name)
+    # Wrap them using the appropriate technique
+    # (which should be either :blacklist or :watchlist)
+    list.each do |subject, methods|
+      send technique, subject, methods
+    end
   end
+
 end

data/lib/cordon/blacklist.rb

@@ -1,30 +1,7 @@
+require File.join(File.dirname(__FILE__), 'method_list')
+
 module Cordon
   module Blacklist
-    TheList = {}
-
-    def self.blacklist_method(subject, method)
-      return if unbound_method(subject, method)  # be idempotent
-
-      # Unbind the original method, and replace it with a wrapper that
-      # checks for permission before binding and calling the original
-      Blacklist.unbind_method(subject, method)
-      subject.__cordon__wrap_method__(method)
-    end
-
-    def self.invoke_method(instance, subject, method, *args, &b)
-      um = unbound_method(subject, method)
-      um.bind(instance).call(*args, &b)
-    end
-
-  protected
-
-    def self.unbind_method(subject, method)
-      um = subject.instance_method(method) # will raise NameError if the method doesn't exist
-      TheList[[subject, method]] = um
-    end
-
-    def self.unbound_method(subject, method)
-      TheList[[subject, method]]
-    end
+    extend MethodList
   end
 end

data/lib/cordon/method_list.rb

@@ -0,0 +1,38 @@
+module Cordon
+  module MethodList
+    def includes?(subject, method)
+      method_list.has_key?([subject, method])
+    end
+
+    def wrap_methods(subject, methods)
+      methods.each do |method|
+        wrap_method(subject, method.to_sym)
+      end
+    end
+
+    def wrap_method(subject, method)
+      return if includes?(subject, method)  # be idempotent
+
+      # Unbind the original method, and replace it with a wrapper that
+      # decides whether to bind and call the original
+      unbind_method(subject, method)
+      subject.__cordon__wrap_method__(method)
+    end
+
+    def invoke_method(instance, subject, method, *args, &b)
+      unbound_method = method_list[[subject, method]]
+      unbound_method.bind(instance).call(*args, &b)
+    end
+
+  protected
+
+    def unbind_method(subject, method)
+      unbound_method = subject.instance_method(method) # will raise NameError if the method doesn't exist
+      method_list[[subject, method]] = unbound_method
+    end
+
+    def method_list
+      @method_list ||= {}
+    end
+  end
+end

data/lib/cordon/sanitaire.rb

@@ -14,8 +14,14 @@ module Cordon
   protected
 
     def __cordon__call_method__(subject, method, *args, &b)
-      ::Cordon::Whitelist.check_permissions(self, subject, method, *args)
-      ::Cordon::Blacklist.invoke_method(self, subject, method, *args, &b)
+      case
+      when Watchlist.includes?(subject, method)
+        ::Cordon::Watchlist.invoke_method(self, subject, method, *args, &b)
+      when Whitelist.admits?(self)
+        ::Cordon::Blacklist.invoke_method(self, subject, method, *args, &b)
+      else
+        raise ::Cordon::Violation.from_invocation(subject, method, args)
+      end
     end
   end
 end

data/lib/cordon/violation.rb

@@ -1,9 +1,37 @@
 module Cordon
   class Violation < Exception
+    SelfRegex = /\/lib\/cordon.*\.rb\:\d+\:in/
+    CustomFilterProcs = []
+
+    def self.add_custom_backtrace_filter(&proc)
+      CustomFilterProcs << proc
+    end
+
+    def self.clear_custom_backtrace_filters
+      CustomFilterProcs.clear
+    end
+
+    def self.from_invocation(subject, method, args)
+      method_descriptor = '%s#%s' % [subject, method]
+      message = '%s(%s)' % [method_descriptor, args.map(&:inspect).join(', ')]
+      new(message).tap { |e| e.method_descriptor = method_descriptor }
+    end
+
+    attr_accessor :method_descriptor
+
     def backtrace
       bt = super
-      bt.shift while bt && bt.first =~ /cordon\.rb\:\d+\:in/
-      bt
+      return if bt.nil?
+
+      # Take anything in 'lib/cordon*.rb' off of the *top* of the backtrace so users don't get distracted by it
+      bt.shift while bt.first =~ SelfRegex
+
+      # Apply any other custom filters to the backtrace before returning it
+      CustomFilterProcs.each do |filter|
+        bt = filter.call(bt)
+      end
+
+      return bt
     end
   end
 end

data/lib/cordon/watchlist.rb

@@ -0,0 +1,50 @@
+require File.join(File.dirname(__FILE__), 'method_list')
+
+module Cordon
+  module Watchlist
+    extend MethodList
+
+    class << self
+      def invoke_method(instance, subject, method, *args, &b)
+        record_incursion(subject, method, args)
+        super
+      end
+
+      def incursions
+        @incursions ||= []
+      end
+
+      def incursion_report
+        report = <<-EOF.strip
+=======================
+Cordon Incursion Report
+=======================
+        EOF
+        n = incursions.length
+        max_width = n.to_s.length
+
+        incursions_by_method = Hash.new { |hash, key| hash[key] = [] }
+        incursions.each do |incursion|
+          incursions_by_method[incursion.method_descriptor] << incursion
+        end
+
+        incursions_by_method.to_a.sort.each do |method_descriptor, incursions|
+          report << "\n\n#{method_descriptor}\n#{'-' * method_descriptor.length}"
+          incursions.each do |incursion|
+            report << "\n" + incursion.backtrace.first.to_s
+          end
+        end
+        report << "\n"
+        report
+      end
+
+    protected
+
+      def record_incursion(subject, method, args)
+        raise Cordon::Violation.from_invocation(subject, method, args)
+      rescue Cordon::Violation => e
+        incursions << e
+      end
+    end
+  end
+end

data/lib/cordon/whitelist.rb

@@ -6,11 +6,8 @@ module Cordon
       TheList << object
     end
 
-    def self.check_permissions(instance, subject, method, *args)
-      allowed = !! TheList.delete(instance)
-      return if allowed
-      message = '%s#%s(%s)' % [subject, method, args.map(&:inspect).join(', ')]
-      raise ::Cordon::Violation, message
+    def self.admits?(instance)
+      !! TheList.delete(instance)
     end
   end
 end

data/test/integration/backtrace_cleaning_test.rb

@@ -17,4 +17,20 @@ class BacktraceCleaningUnitTest < CordonUnitTest
     failure_message << (e.backtrace[0..3] + ['(rest of backtrace omitted)']).map { |e| '  ' + e }.join("\n")
     refute e.backtrace.first.include?('cordon.rb:'), failure_message
   end
+
+  def test_custom_cleaning
+    Cordon.filter_violation_backtrace { |backtrace|
+      project_root = File.expand_path(File.join(File.dirname(__FILE__), *%w[.. ..]))
+      in_project = Regexp.new(project_root)
+      backtrace.select { |line| line =~ in_project }
+    }
+
+    foo.verboten_method_for_backtrace
+
+  rescue Cordon::Violation => e
+    refute e.backtrace.any? { |line| line =~ /\/unit\.rb:/ }, "Custom backtrace filter did not work"
+
+  ensure
+    Cordon.dont_filter_violation_backtrace!
+  end
 end

data/test/integration/watchlist_test.rb

@@ -0,0 +1,103 @@
+require File.join(File.dirname(__FILE__), 'integration_test_helper')
+
+$shady_method_call_count = 0
+module Kernel
+  def shady_method
+    # we are a hedge. move along.
+    $shady_method_call_count += 1
+  end
+
+  def dubious_method
+    # nothing to see here either
+  end
+end
+
+# In addition to blacklisting methods, Cordon can also place them on a watchlist.
+# This will track invocations for later reporting.
+# (It's not nearly as glamorous as the Bond movies would have you believe.)
+Cordon.watchlist Kernel, [:shady_method, :dubious_method]
+
+class WatchlistTest < CordonUnitTest
+  def method_one
+    shady_method; @method_one_line = __LINE__
+  end
+  def method_two
+    shady_method; @method_two_line = __LINE__
+  end
+  def method_three
+    dubious_method; @method_three_line = __LINE__
+  end
+
+  def setup
+    $shady_method_call_count = 0
+    Cordon.filter_violation_backtrace do |backtrace|
+      current_file = File.expand_path(__FILE__)
+      in_file = Regexp.new(current_file)
+      backtrace.select { |line| line =~ in_file }
+    end
+  end
+
+  def teardown
+    Cordon.dont_filter_violation_backtrace!
+    Cordon.incursions.clear
+  end
+
+  def test_shady_calls_are_allowed
+    method_one; assert_equal 1, $shady_method_call_count
+    method_one; assert_equal 2, $shady_method_call_count
+    method_two; assert_equal 3, $shady_method_call_count
+  end
+  
+  def test_shady_calls_are_counted
+    assert Cordon.incursions.empty?
+
+    method_one; assert_equal 1, Cordon.incursions.length
+    method_one; assert_equal 2, Cordon.incursions.length
+    method_two; assert_equal 3, Cordon.incursions.length
+  end
+  
+  def test_shady_calls_are_logged
+    assert Cordon.incursions.empty?
+
+    method_one; invocation_1_line = __LINE__
+    method_one; invocation_2_line = __LINE__
+    method_two; invocation_3_line = __LINE__
+
+    i1, i2, i3 = *Cordon.incursions
+
+    # Quick sanity check:  make sure we're only looking at backtraces in the current file (see #setup)
+    assert i1.backtrace.length == 2
+    assert i2.backtrace.length == 2
+    assert i3.backtrace.length == 2
+
+    # NOTE: using assert_match prints a weird MiniTest error
+
+    # First line should be the actual invocation of #shady_method
+    assert i1.backtrace[0] =~ /watchlist_test.rb:#{@method_one_line}:in `method_one'$/, i1.backtrace[0]
+    assert i2.backtrace[0] =~ /watchlist_test.rb:#{@method_one_line}:in `method_one'$/, i2.backtrace[0]
+    assert i3.backtrace[0] =~ /watchlist_test.rb:#{@method_two_line}:in `method_two'$/, i3.backtrace[0]
+
+    # Second line should be the place where method_(one|two) was called
+    assert i1.backtrace[1] =~ /watchlist_test.rb:#{invocation_1_line}:in `test_shady_calls_are_logged'$/, i1.backtrace[1]
+    assert i2.backtrace[1] =~ /watchlist_test.rb:#{invocation_2_line}:in `test_shady_calls_are_logged'$/, i2.backtrace[1]
+    assert i3.backtrace[1] =~ /watchlist_test.rb:#{invocation_3_line}:in `test_shady_calls_are_logged'$/, i3.backtrace[1]
+  end
+
+  def test_incursion_report
+    method_one
+    method_two
+    method_one
+    method_two
+    method_three
+
+    report = Cordon.incursion_report
+
+    assert report =~ /Kernel#shady_method/
+    assert report =~ /Kernel#dubious_method/
+
+    assert report =~ /watchlist_test.rb:#{@method_one_line}:in `method_one'$/
+    assert report =~ /watchlist_test.rb:#{@method_one_line}:in `method_one'$/
+    assert report =~ /watchlist_test.rb:#{@method_two_line}:in `method_two'$/
+    assert report =~ /watchlist_test.rb:#{@method_three_line}:in `method_three'$/
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cordon
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-09 00:00:00.000000000Z
+date: 2012-03-15 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &2156968780 !ruby/object:Gem::Requirement
+  requirement: &2155010720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.12'
   type: :development
   prerelease: false
-  version_requirements: *2156968780
+  version_requirements: *2155010720
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2156967060 !ruby/object:Gem::Requirement
+  requirement: &2155010220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2156967060
+  version_requirements: *2155010220
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2156964940 !ruby/object:Gem::Requirement
+  requirement: &2155009740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 1.8.3
   type: :development
   prerelease: false
-  version_requirements: *2156964940
+  version_requirements: *2155009740
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &2156962400 !ruby/object:Gem::Requirement
+  requirement: &2155009240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 0.10.3
   type: :development
   prerelease: false
-  version_requirements: *2156962400
+  version_requirements: *2155009240
 - !ruby/object:Gem::Dependency
   name: ruby-debug19
-  requirement: &2156960720 !ruby/object:Gem::Requirement
+  requirement: &2155008740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156960720
+  version_requirements: *2155008740
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2156958500 !ruby/object:Gem::Requirement
+  requirement: &2155008260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156958500
+  version_requirements: *2155008260
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &2156956460 !ruby/object:Gem::Requirement
+  requirement: &2155007680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156956460
+  version_requirements: *2155007680
 description: A bit of an experiment, really
 email: geeksam@gmail.com
 executables: []
@@ -103,18 +103,21 @@ files:
 - cordon.gemspec
 - lib/cordon.rb
 - lib/cordon/blacklist.rb
+- lib/cordon/method_list.rb
 - lib/cordon/sanitaire.rb
 - lib/cordon/violation.rb
+- lib/cordon/watchlist.rb
 - lib/cordon/whitelist.rb
 - test/framework_integration/minitest_spec_spec.rb
 - test/framework_integration/rspec_spec.rb
 - test/helper.rb
 - test/integration/backtrace_cleaning_test.rb
-- test/integration/cordon_basic_examples_test.rb
-- test/integration/cordon_customization_test.rb
-- test/integration/cordon_default_behavior_test.rb
-- test/integration/cordon_edge_cases_test.rb
+- test/integration/basic_examples_test.rb
+- test/integration/customization_test.rb
+- test/integration/default_behavior_test.rb
+- test/integration/edge_cases_test.rb
 - test/integration/integration_test_helper.rb
+- test/integration/watchlist_test.rb
 homepage: http://github.com/geeksam/cordon
 licenses:
 - WTFPL
@@ -130,7 +133,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2252535489042103113
+      hash: 3052646131815485488
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: