state_validations 0.2.0

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+*.swp
+.rvmrc

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 PagerDuty, Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# StateValidations
+
+**Current version:** 0.2.0
+
+The StateValidations gem is a collection of two Validators that aid in
+verifying the integrity of a state history association. As defined here, a
+state history is a collection of entries, each with start and end time
+attributes.
+
+One validator provided is the aptly-named StateHistoryValidator. This Validator
+examines a state history holistically checking for a variety of issues. These 
+issues include:
+
+* Overlaps: the time ranges of two consecutive entries overlap
+* Gaps: the time ranges of two consecutive entries are not continuous
+* Self-transitions: two continuous consecutive entries are equivalent in state
+* Simultaneous states: an entry that is not the last entry has not ended (i.e.
+the entry's end time is `nil`)
+* Ended state histories: the last entry has ended (i.e. last entry's end time
+is `nil`)
+
+The user of this validator can disable any combination of these checks as he or
+she wishes through the `:allow` option.
+
+The other validator provided is the StateHistoryEntryValidator. This Validator
+examines each state history entry on its own, checking for these issues:
+
+* Zero-length entries: the entry begins and ends at the same time
+* Ends before starting: the entry ends before it starts (end < start)
+
+As with the first validator, the user can disable any combination of these
+checks.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'state_validations'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ git clone git://github.com/PagerDuty/state-history-validator.git
+    $ rake build
+    $ gem install pkg/state_validations-(version).gem
+
+## Usage
+
+### Examples
+
+#### StateHistoryValidator
+Let's say that we want to check the integrity of `:state_history_entries`.
+This is how we might call the validator:
+
+    validate_state_history :state_history_entries,
+      :self_transition_match => [:state_id],
+      :allow => [:gaps]
+
+Here, our validator will allow for gaps in the state history entries. It
+will look for self-transitions depending on whether the `:state_id`
+attribute of two consecutive entries match.
+
+#### StateHistoryEntryValidator
+Let's say we want to validate an entry, but we don't particularly care
+about zero-entries. In addition, our entry uses the attribute `:begin` to
+indicate its start time attribute. This is how we might use the validator:
+
+    validate_state_history_entry
+      :start => :begin
+      :allow => [:zero_duration]
+
+Note that we omitted the comma after `validate_state_history_entry`.
+
+The StateHistoryEntryValidator requires that the receiving class validate
+for the presence of the `:start` attribute. The `validate_state_history_entry`
+construct, which is the recommended way to call this validator, performs this
+validation automatically.
+
+### Interface
+With these examples in mind, here is the full documentation on every option
+that can be toggled.
+
+#### StateHistoryValidator
+* `:start` -- (default = `:start`) Specifies the attribute referring to the
+starting time of each entry
+* `:end` -- (default = `:end`) Specifies the attribute referring to the
+ending time of each entry
+* `:order` -- (default = `#{start} ASC, ISNULL(#{end}) ASC, #{end} ASC`)
+Specifies the SQL order by which the validator will sort all entries in the
+state history. This is essential in ensuring that the validator obtains the
+correct chronological order of entries so that it can properly check for
+issues. By default, the validator sorts in ascending order of starting 
+time. If the start times for two entries are equal, it will then sort by
+end times (pushing `nil` ends to the bottom).
+* `:self_transition_match` -- (default = `[]`) Specifies the attributes to
+check two states for equality. This is used when checking for self-transitions.
+If self-transitions are allowed, this option has no effect. If this option
+is left to its default value of an empty array, the validator will not check
+for self-transitions.
+* `:allow` -- (default = `[]`) Specifies issues to be ignored by the validator.
+This is specified as a list of issues. By default, all checks are performed.
+The issues that can be specified are:
+    * `:gaps` -- Ignore gaps
+    * `:overlaps` -- Ignore overlaps
+    * `:self_transitions` -- Ignore two consecutive equal states. As a side
+    note, two equal states separated by a gap are not considered to be in
+    self-transition.
+    * `:active_middle_states` -- Ignore the presence of an active state in the
+    middle of a state history. An active state is defined by the state's `:end`
+    attribute being `nil`.
+    This excludes the final state.
+    * `:inactive_end_state` -- Ignore the lack of a final active ending state.
+    Using our earlier definition, this means that the last entry does not have
+    `nil` as the value of its `:end` attribute.
+
+#### StateHistoryEntryValidator
+* `:start` -- (default = `:start`) Specifies the attribute referring to the
+starting time of this entry
+* `:end` -- (default = `:end`) Specifies the attribute referring to the ending
+time of this entry
+* `:allow` -- (default = `[]`) Specifies issues to be ignored by the validator.
+    * `:zero_duration` -- Ignore start time equal to end time
+    * `:end_before_start` -- Ignore end time less than start time
+      
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,41 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+desc 'Run shoulda unit tests'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+
+# Thanks, jekyll, for having your Rakefile on Github
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read(gemspec_file)[/^\s*gem\.version\s*=\s*.*/]
+  line.match(/.*gem\.version\s*=\s*['"](.*)['"]/)[1]
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+task :build do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+task :push do
+  sh "gem push pkg/#{gem_file}"
+end

data/lib/active_model/validations/helper_methods.rb

@@ -0,0 +1,24 @@
+require 'active_model/validations'
+
+module ActiveModel
+  module Validations
+
+    module HelperMethods
+      def validate_state_history_entry(options = {})
+        start_attr = options[:start] || :start
+        validates start_attr, :presence => true
+
+        validates_with StateHistoryEntryValidator, options
+      end
+
+
+      def validate_state_history(association, options = {})
+        params = { :association => association }
+        params.merge!(options)
+        validates_with StateHistoryValidator, params
+      end
+    end
+
+  end
+end
+

data/lib/active_model/validations/state_history_entry_validator.rb

@@ -0,0 +1,40 @@
+module ActiveModel
+  module Validations
+
+    class StateHistoryEntryValidator < ActiveModel::Validator
+      def initialize(options = {})
+        super
+
+        @start = options[:start] || :start
+        @end   = options[:end]   || :end
+        @allow = options[:allow] || []
+      end
+
+      def validate(record)
+        non_zero?(record)         unless @allow.include? :zero_duration
+        start_before_end?(record) unless @allow.include? :end_before_start
+
+        return
+      end
+
+      private
+
+      def non_zero?(record)
+        start = record[@start]
+        _end  = record[@end]
+        if start == _end
+          record.errors[:base] << "Start time (#{start}) is equal to end (#{_end})"
+        end
+      end
+
+      def start_before_end?(record)
+        start = record[@start]
+        _end  = record[@end]
+        if !_end.blank? && start > _end
+          record.errors[:base] << "Start time (#{start}) is later than end time (#{_end})"
+        end
+      end
+    end
+
+  end
+end

data/lib/active_model/validations/state_history_validator.rb

@@ -0,0 +1,118 @@
+module ActiveModel
+  module Validations
+
+    class StateHistoryValidator < ActiveModel::Validator
+      def initialize(options = {})
+        super
+
+        @association = options[:association]
+
+        @start = options[:start] || :start
+        @end   = options[:end]   || :end
+        @order = options[:order] || "#{@start.to_s} ASC, ISNULL(#{@end}) ASC, #{@end} ASC"
+        @allow = options[:allow] || []
+        @match = options[:self_transition_match] || []
+      end
+
+      def validate(record)
+        entries = record.send(@association)
+        sorted_history = entries.order(@order)
+
+        return if sorted_history.blank?
+
+        if !@allow.include? :inactive_end_state
+          valid = last_end_nil?(sorted_history, record.errors)
+          return unless valid
+        end
+
+        no_self_trans = no_gaps = no_overlaps = no_nils = true
+        sorted_history.each_cons(2) do |a|
+          this_entry = a[0]
+          next_entry = a[1]
+
+          if !@allow.include? :self_transitions
+            no_self_trans = no_self_transitions?(this_entry, next_entry, record.errors)
+          end
+
+          if !@allow.include? :gaps
+            no_gaps = no_gaps?(this_entry, next_entry, record.errors)
+          end
+
+          if !@allow.include? :overlaps
+            no_overlaps = no_overlaps?(this_entry, next_entry, record.errors)
+          end
+
+          if !@allow.include? :active_middle_states
+            no_nils = no_intervening_nils?(this_entry, record.errors)
+          end
+
+          return unless no_self_trans && no_gaps && no_overlaps && no_nils
+        end
+      end
+
+      private
+
+      def last_end_nil?(history, errors)
+        last = history.last
+
+        if !last[@end].nil?
+          errors[:base] << "no nil ending"
+          return false
+        end
+
+        true
+      end
+
+      def no_self_transitions?(this_entry, next_entry, errors)
+        if matches?(this_entry, next_entry) && this_entry[@end] == next_entry[@start]
+          errors[:base] << "self-transition found"
+          return false
+        end
+
+        true
+      end
+
+      def no_gaps?(this_entry, next_entry, errors)
+        if !this_entry[@end].nil? && next_entry[@start] > this_entry[@end]
+          errors[:base] << "Gap found"
+          return false
+        end
+
+        true
+      end
+
+      def no_overlaps?(this_entry, next_entry, errors)
+        if !this_entry[@end].nil? && next_entry[@start] < this_entry[@end]
+          errors[:base] << "Overlap found"
+          return false
+        end
+
+        true
+      end
+
+      # This doesn't get invoked on the very last entry, so we should be safe
+      def no_intervening_nils?(this_entry, errors)
+        if this_entry[@end].blank?
+          errors[:base] << "Found nil end in middle of state history"
+          return false
+        end
+
+        true
+      end
+
+      # Match two entries based on the specified attributes in @match
+      def matches?(entry1, entry2)
+        return false if @match.size == 0
+
+        @match.each do |attr|
+          return false if entry1[attr] != entry2[attr]
+        end
+
+        true
+      end
+
+    end
+
+  end
+end
+

data/lib/state_validations.rb

@@ -0,0 +1,6 @@
+require 'active_model/validations/state_history_validator'
+require 'active_model/validations/state_history_entry_validator'
+require 'active_model/validations/helper_methods'
+
+module StateValidations
+end

data/state_validations.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+
+# Note to self: the module file in lib/ needs to have the same name as this file
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Daniel Ge", "PagerDuty, Inc."]
+  gem.email         = ["daniel@pagerduty.com"]
+  gem.summary       = "State History and State History Entry Validators"
+  gem.description   = "A gem that verifies the integrity of a state history"
+  gem.homepage      = "https://github.com/PagerDuty/state-history-validator"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "state_validations"
+  gem.require_paths = ["lib"]
+  gem.version       = "0.2.0"
+
+  # Dependencies
+  gem.add_runtime_dependency "activemodel", ">= 3.0.0"
+  gem.add_runtime_dependency "activesupport", ">= 3.0.0"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "test-unit", "= 2.2"
+  gem.add_development_dependency "mocha"
+  gem.add_development_dependency "shoulda"
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require 'mocha/integration/test_unit'
+require 'active_support/core_ext'
+require 'active_model'
+
+require 'state_validations'

data/test/unit/helper_methods_test.rb

@@ -0,0 +1,45 @@
+require 'test_helper'
+
+class HelperMethodsTest < ActiveSupport::TestCase
+  context "The helper methods on a perfectly valid state history" do
+    setup do
+      now = DateTime.new(2011, 2, 3, 5, 8, 13)
+      @starts = [now, now + 2.months, now + 3.months, now + 5.months]
+      @ends   = [now + 2.months, now + 3.months, now + 5.months, nil]
+    end
+
+    should "simply work" do
+      record_entries = []
+      @starts.each_with_index do |start, i|
+        _end = @ends[i]
+        id = i
+        entry = RecordEntry.new(start, _end, id)
+
+        assert entry.valid?
+
+        record_entries << entry
+      end
+
+      record_entries.stubs(:order).with("start ASC, ISNULL(end) ASC, end ASC").returns(record_entries)
+      record_entries.stubs(:all).returns(record_entries)
+
+      record = Record.new(record_entries)
+
+      assert record.valid?
+    end
+  end
+
+end
+
+class Record < Struct.new(:record_entries)
+  include ActiveModel::Validations
+
+  validate_state_history :record_entries,
+    :self_transition_match => [:id]
+end
+
+class RecordEntry < Struct.new(:start, :end, :id)
+  include ActiveModel::Validations
+
+  validate_state_history_entry
+end

data/test/unit/state_history_entry_validator_test.rb

@@ -0,0 +1,101 @@
+require 'test_helper'
+
+module ActiveModel
+  module Validations
+
+    class StateHistoryEntryValidatorTest < ActiveSupport::TestCase
+      context "An \"perfect\" account state history entry" do
+        setup do
+          @now = DateTime.new(2011, 2, 3, 5, 8, 13)
+        end
+
+        should "be valid by default with no checks disabled" do
+          entry = ValidatableEntry.new(@now, @now + 1.days)
+
+          validator = StateHistoryEntryValidator.new
+          validator.validate(entry)
+
+          assert !entry.errors.any?
+        end
+
+        should "be valid if :start and :end are changed" do
+          MockEntry = Struct.new(:begin, :finish)
+          MockEntry.class_eval do
+            include ActiveModel::Validations
+          end
+          entry = MockEntry.new(@now, @now + 1.days)
+
+          validator = StateHistoryEntryValidator.new(
+            :start => :begin,
+            :end => :finish
+          )
+          validator.validate(entry)
+
+          assert !entry.errors.any?
+        end
+
+        should "be valid even if the end is nil" do
+          entry = ValidatableEntry.new(@now, nil)
+
+          validator = StateHistoryEntryValidator.new
+          validator.validate(entry)
+
+          assert !entry.errors.any?
+        end
+      end
+
+      context "An account state history entry where start == end" do
+        setup do
+          @now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          @entry = ValidatableEntry.new(@now, @now)
+        end
+
+        should "not be valid with no checks disabled" do
+          validator = StateHistoryEntryValidator.new
+          validator.validate(@entry)
+
+          assert @entry.errors.any?
+        end
+
+        should "be valid with :zero_duration allowed" do
+          validator = StateHistoryEntryValidator.new(
+            :allow => [:zero_duration]
+          )
+          validator.validate(@entry)
+
+          assert !@entry.errors.any?
+        end
+      end
+
+      context "An account state history entry where start > end" do
+        setup do
+          @now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          @entry = ValidatableEntry.new(@now + 1.days, @now)
+        end
+
+        should "not be valid with no checks disabled" do
+          validator = StateHistoryEntryValidator.new
+          validator.validate(@entry)
+
+          assert @entry.errors.any?
+        end
+
+        should "be valid with :end_before_start allowed" do
+          validator = StateHistoryEntryValidator.new(
+            :allow => [:end_before_start]
+          )
+          validator.validate(@entry)
+
+          assert !@entry.errors.any?
+        end
+      end
+
+      private
+
+      class ValidatableEntry < Struct.new(:start, :end)
+        include ActiveModel::Validations
+      end
+    end
+
+  end
+end

data/test/unit/state_history_validator_test.rb

@@ -0,0 +1,308 @@
+require 'test_helper'
+
+module ActiveModel
+  module Validations
+
+    class StateHistoryValidatorTest < ActiveSupport::TestCase
+      context "A perfectly valid state history" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          @starts = [now, now + 2.months, now + 3.months, now + 5.months]
+          @ends   = [now + 2.months, now + 3.months, now + 5.months, nil]
+        end
+
+        should "simply be valid with the default options" do
+          state_history = mock_state_history(@starts, @ends) do |entry, i|
+            entry[:other_id] = i + 1
+          end
+
+          record = Validatable.new(state_history)
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id, :other_id]
+          )
+          validator.validate(record)
+
+          assert !record.errors.any?
+        end
+
+        should "be valid if we only set a different start and end name" do
+          MockEntry = Struct.new(:begin, :finish, :id, :other_id)
+          state_history = mock_state_history(@starts, @ends, nil,
+                                             {:entry_class => MockEntry,
+                                              :start => :begin,
+                                              :end => :finish}) do |entry, i|
+            entry[:other_id] = i + 1
+          end
+
+          record = Validatable.new(state_history)
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :start => :begin,
+            :end   => :finish,
+            :self_transition_match => [:id, :other_id]
+          )
+          validator.validate(record)
+
+          assert !record.errors.any?
+        end
+
+      end
+
+      context "A \"perfect\" state history with a self-transition" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          starts = [now, now + 2.months, now + 3.months, now + 5.months]
+          ends   = [now + 2.months, now + 3.months, now + 5.months, nil]
+          ids = [0, 1, 1, 2]
+          other_id = [1, 1, 1, 2]
+
+          state_history = mock_state_history(starts, ends, ids) do |entry, i|
+            entry[:other_id] = other_id[i]
+          end
+
+          @record = Validatable.new(state_history)
+        end
+
+        should "be invalid with nothing allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id, :other_id]
+          )
+          validator.validate(@record)
+
+          assert @record.errors.any?
+        end
+
+        should "be valid with :self_transitions allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id, :other_id],
+            :allow => [:self_transitions]
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+
+        should "be valid if no :self_transition_match is specified and nothing is allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+      end
+
+      context "A \"perfect\" state history with a non-nil end" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          starts = [now, now + 2.months, now + 3.months, now + 5.months]
+          ends   = [now + 2.months, now + 3.months, now + 5.months, now + 8.months]
+
+          @state_history = mock_state_history(starts, ends, nil) {}
+
+          @record = Validatable.new(@state_history)
+        end
+
+        should "not be valid with nothing allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id]
+          )
+          validator.validate(@record)
+
+          assert @record.errors.any?
+        end
+
+        should "be valid with :inactive_end_state allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id],
+            :allow => [:inactive_end_state]
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+      end
+
+      context "A state history with overlaps" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          starts = [now, now + 2.months, now + 3.months, now + 5.months]
+          ends   = [now + 2.months, now + 3.months, now + 6.months, nil]
+
+          @state_history = mock_state_history(starts, ends) {}
+
+          @record = Validatable.new(@state_history)
+        end
+
+        should "not be valid with nothing allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id]
+          )
+          validator.validate(@record)
+
+          assert @record.errors.any?
+        end
+
+        should "be valid with :overlaps allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id],
+            :allow => [:overlaps]
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+      end
+
+      context "A state history with gaps" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          starts = [now, now + 2.months, now + 3.months, now + 5.months]
+          ends   = [now + 2.months, now + 3.months, now + 4.months, nil]
+
+          state_history = mock_state_history(starts, ends) {}
+          @record = Validatable.new(state_history)
+        end
+
+        should "not be valid with nothing allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id]
+          )
+          validator.validate(@record)
+
+          assert @record.errors.any?
+        end
+
+        should "be valid with :gaps allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id],
+            :allow => [:gaps]
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+      end
+
+      context "A state history with nil `:ends` in the middle" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          @starts = [now, now + 2.months, now + 3.months, now + 5.months]
+          @ends   = [now + 2.months, nil, now + 5.months, nil]
+
+          state_history = mock_state_history(@starts, @ends) {}
+          @record = Validatable.new(state_history)
+        end
+
+        should "not be valid with nothing allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id]
+          )
+          validator.validate(@record)
+
+          assert @record.errors.any?
+        end
+
+        should "be valid with :active_middle_states allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id],
+            :allow => [:active_middle_states]
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+      end
+
+      context "A state history with two consecutive equivalent states separated by a gap" do
+        setup do
+          now = DateTime.new(2011, 2, 3, 5, 8, 13)
+          @starts = [now, now + 2.months]
+          @ends   = [now + 1.months, nil]
+          @id     = [0, 0]
+
+          state_history = mock_state_history(@starts, @ends, @id) {}
+
+          @record = Validatable.new(state_history)
+        end
+
+        should "not be valid with nothing allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id]
+          )
+          validator.validate(@record)
+
+          assert @record.errors.any?
+        end
+
+        should "be valid with :gaps allowed" do
+          validator = StateHistoryValidator.new(
+            :association => :state_history_entries,
+            :self_transition_match => [:id],
+            :allow => [:gaps]
+          )
+          validator.validate(@record)
+
+          assert !@record.errors.any?
+        end
+      end
+
+      private
+
+      class Validatable < Struct.new(:state_history_entries)
+        include ActiveModel::Validations
+      end
+
+      class ValidatableEntry < Struct.new(:start, :end, :id, :other_id)
+      end
+
+      # fake the entries.order(@order).all call
+      def state_history_stub(state_history, options = {})
+        start_attr = options[:start] || :start
+        end_attr = options[:end] || :end
+        sort_dir = options[:sort_dir] || "ASC"
+
+        order_by = options[:order] || 
+          "#{start_attr} #{sort_dir}, ISNULL(#{end_attr}) #{sort_dir}, #{end_attr} #{sort_dir}"
+
+        state_history.stubs(:order).with(order_by).returns(state_history)
+        state_history.stubs(:all).returns(state_history)
+      end
+
+      # Set up a state_history with fake objects and then yield to allow further customization
+      def mock_state_history(starts, ends, ids = nil, options = {})
+        stub_history = (options[:stub_history].nil?) ? true : options[:stub_history]
+        entry_class = (options[:entry_class].nil?) ? ValidatableEntry : options[:entry_class]
+
+        state_history = []
+        starts.each_with_index do |start, i|
+          _end = ends[i]
+          id = (ids.nil?) ? i : ids[i]
+          entry = entry_class.new(start, _end, id)
+
+          yield entry, i
+
+          state_history << entry
+        end
+
+        state_history_stub(state_history, options) if stub_history
+
+        state_history
+      end
+
+    end
+
+  end
+end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification 
+name: state_validations
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Daniel Ge
+- PagerDuty, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-18 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  prerelease: false
+  type: :runtime
+  name: activemodel
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  prerelease: false
+  type: :runtime
+  name: activesupport
+  requirement: *id002
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  prerelease: false
+  type: :development
+  name: rake
+  requirement: *id003
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 2
+        - 2
+        version: "2.2"
+  prerelease: false
+  type: :development
+  name: test-unit
+  requirement: *id004
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  prerelease: false
+  type: :development
+  name: mocha
+  requirement: *id005
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  prerelease: false
+  type: :development
+  name: shoulda
+  requirement: *id006
+description: A gem that verifies the integrity of a state history
+email: 
+- daniel@pagerduty.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/active_model/validations/helper_methods.rb
+- lib/active_model/validations/state_history_entry_validator.rb
+- lib/active_model/validations/state_history_validator.rb
+- lib/state_validations.rb
+- state_validations.gemspec
+- test/test_helper.rb
+- test/unit/helper_methods_test.rb
+- test/unit/state_history_entry_validator_test.rb
+- test/unit/state_history_validator_test.rb
+homepage: https://github.com/PagerDuty/state-history-validator
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: State History and State History Entry Validators
+test_files: 
+- test/test_helper.rb
+- test/unit/helper_methods_test.rb
+- test/unit/state_history_entry_validator_test.rb
+- test/unit/state_history_validator_test.rb