kevintyll-ssn_validator 0.1.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.1.0 2009-04-14
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,17 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+generators/ssn_validator_migration/templates/migration.rb
+generators/ssn_validator_migration/ssn_validator_migration_generator.rb
+lib/ssn_validator/models/ssn_high_group_code.rb
+lib/ssn_validator/models/ssn_validator.rb
+lib/ssn_validator.rb
+lib/tasks/ssn_validator.rake
+script/console
+script/destroy
+script/generate
+test/test_helper.rb
+test/test_ssn_validator.rb
+test/test_ssn_high_group_code.rb

data/PostInstall.txt

@@ -0,0 +1,8 @@
+
+For more information on ssn_validator, see http://kevintyll.github.com/ssn_validator/
+
+* To create the necessary db migration, from the command line, run:  script/generate ssn_validator_migration
+* To load your table with the current SSN data, from the command line, run:  rake ssn_validator:update_data
+* The SSN data is updated monthly, so you'll want to run this rake task monthly to keep your validations accurate.
+
+

data/README.rdoc

@@ -0,0 +1,66 @@
+= ssn_validator
+
+* http://kevintyll.github.com/ssn_validator/
+
+== DESCRIPTION:
+
+A ruby gem that validates whether an SSN has likely been issued or not.
+
+
+== FEATURES/PROBLEMS:
+
+* Validates the likelyhood that an SSN has been issued to someone.
+
+* What it cannot do:
+    Validate that an SSN actually belongs to a particular person.
+
+* What it's planned to do if I can find the data:
+    Determine when an SSN was issued.  This can be used to further validate an SSN by comparing it to a Date of Birth.
+    Check the Death Master File if the SSN belongs to a dead person.
+
+== SYNOPSIS:
+
+  Just instantiate the object with an SSN.
+    ssn = SsnValidator::Ssn.new('123-45-6789')
+
+  Then check if it's valid
+    ssn.valid?
+
+  You can check the errors array to see why it's not valid.
+    ssn.errors
+
+== REQUIREMENTS:
+
+* Rails 2.0.0 or greater
+
+== INSTALL:
+
+* sudo gem install kevintyll-ssn_validator
+* To create the necessary db migration, from the command line, run:  script/generate ssn_validator_migration
+* To load your table with the current SSN data, from the command line, run:  rake ssn_validator:update_data
+* The SSN data is updated monthly, so you'll want to run this rake task monthly to keep your validations accurate.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Kevin Tyll
+
+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/Rakefile

@@ -0,0 +1,25 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/ssn_validator'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('ssn_validator', SsnValidator::VERSION) do |p|
+  p.developer('Kevin Tyll', 'kevintyll@gmail.com')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt'
+   p.extra_deps         = [
+     ['activerecord','>= 2.0.0'],
+   ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+

data/generators/ssn_validator_migration/ssn_validator_migration_generator.rb

@@ -0,0 +1,12 @@
+class SsnValidatorMigrationGenerator < Rails::Generator::Base
+  def manifest 
+    record do |m|
+      #m.directory File.join('db')
+      m.migration_template 'migration.rb', 'db/migrate' 
+    end 
+  end
+  
+  def file_name
+    "create_ssn_validator_tables"
+  end
+end

data/generators/ssn_validator_migration/templates/migration.rb

@@ -0,0 +1,18 @@
+class CreateSsnValidatorTables < ActiveRecord::Migration
+  
+  def self.up
+    create_table :ssn_high_group_codes do |t|
+      t.date      :as_of
+      t.string    :area
+      t.string    :group
+      t.timestamps
+    end
+    
+    add_index :ssn_high_group_codes, [:area]
+    add_index :ssn_high_group_codes, [:area, :as_of]
+  end
+  
+  def self.down
+    drop_table :ssn_high_group_codes
+  end
+end

data/lib/ssn_validator/models/ssn_high_group_code.rb

@@ -0,0 +1,96 @@
+require 'activerecord'
+require 'net/http'
+class SsnHighGroupCode < ActiveRecord::Base
+
+  ###############
+  #class mehtods#
+  ###############
+
+  def self.load_historical_high_group_codes_file
+    ['Jan','Feb','Mar','Apr','May','June','July','Aug','Sept','Oct','Nov','Dec'].each do |month|
+      (1..10).each do |day|
+        string_day = day.to_s
+        string_day.insert(0,'0') if day < 10
+        current_year = Date.today.year
+        #(1932..current_year).each do |year|
+        [2003].each do |year|
+          string_year = year.to_s.last(2)
+          ['','corrected'].each do |mod|
+            ['ssns','ssnvs'].each do |url_mod|
+              file_name = "HG#{month}#{string_day}#{string_year}#{mod}.txt"
+              text = Net::HTTP.get(URI.parse("http://www.socialsecurity.gov/employer/#{url_mod}/#{file_name}"))
+              puts file_name.inspect
+              puts '@@@@@@@@@ found file_name = ' + file_name.inspect unless text.include? 'File Not Found'
+            end
+          end
+          
+        end
+      end
+      
+    end
+  end
+
+  #Loads the most recent file from http://www.socialsecurity.gov/employer/ssns/highgroup.txt
+  def self.load_current_high_group_codes_file
+    text = Net::HTTP.get(URI.parse('http://www.socialsecurity.gov/employer/ssns/highgroup.txt'))
+    create_records(parse_text(text),extract_as_of_date(text))
+  end
+
+  def self.already_loaded?(file_as_of_date)
+    self.find_by_as_of(file_as_of_date)
+  end
+  ###################
+  #end class mehtods#
+  ###################
+
+  ##################
+  #instance mehtods#
+  ##################
+
+  
+
+  ######################
+  #end instance mehtods#
+  ######################
+  private
+
+  def self.create_records(area_groups,file_as_of)
+    if already_loaded?(file_as_of)
+      "File as of #{file_as_of} has already been loaded."
+    else
+      area_groups.each do |area_group|
+        self.create(area_group.merge!(:as_of => file_as_of.to_s(:db)))
+      end
+      "File as of #{file_as_of} loaded."
+    end
+  end
+
+  #extract the date from the file in the format mm/dd/yy
+  def self.extract_as_of_date(text)
+    as_of_start_index = text =~ /\d\d\/\d\d\/\d\d/
+    ::Date.new(*::Date._parse($&,true).values_at(:year, :mon, :mday)) unless as_of_start_index.nil?
+  end
+
+  #The formatting of the file is a little bit messy. Sometimes tabs are
+  #used as delimiters and sometimes spaces are used as delimiters. Also, the asterisks indicating recent changes are not
+  #necessary for our purposes
+  #Returns an array of hashes.
+  def self.parse_text(text)
+    text.gsub!('*',' ')
+    text.gsub!(/\t/, ' ')
+    text_array = text.split(/\n/).compact
+    area_groups = []
+    text_array.each do |t|
+      t.gsub!(/\s+/,' ')
+      next if t =~ /[[:alpha:]]/ #skip over the header lines
+
+      if t =~ /\d\d\d \d\d/ #we want the lines with area group pairs
+        t.gsub(/\d\d\d \d\d/) do |s|
+          area_group = s.split(' ')
+          area_groups << {:area => area_group.first, :group => area_group.last}
+        end
+      end
+    end
+    return area_groups
+  end
+end

data/lib/ssn_validator/models/ssn_validator.rb

@@ -0,0 +1,79 @@
+module SsnValidator
+  class Ssn
+
+    attr_reader :ssn,:area,:group,:serial_number
+    attr_reader :errors
+
+
+    def initialize(ssn)
+      @errors = []
+      ssn = ssn.to_s
+      if ssn =~ /-/ && ssn !~ /\d\d\d-\d\d-\d\d\d\d/
+        @errors << 'Hyphen misplaced.'
+      end
+
+      ssn.gsub!('-','')
+      if ssn.to_s.size != 9
+        @errors <<  'SSN not 9 digits long.'
+      end
+
+      if ssn =~ /\D/
+        @errors << 'Non-digit found.'
+      end
+
+      #known dummy numbers
+      if ["078051120","111111111","123456789","219099999","999999999"].include? ssn || (ssn >= "987654320" and ssn <= "987654329")
+        @errors << "Known dummy SSN."
+      end
+      #known invalid area, group and serial numbers
+      if ssn =~ /\d{3}00\d{4}|0000\Z/
+        @errors << "Invalid group or serial number."
+      end
+
+      @ssn = ssn
+      @area = ssn.first(3)
+      @group = ssn[3,2]
+      @serial_number = ssn.last(4)
+
+      if @errors.empty?
+        @ssn_high_group_code = SsnHighGroupCode.find_by_area(@area, :order => 'as_of desc')
+        if @ssn_high_group_code.nil?
+          @errors << "Area '#{@area}' has not been assigned."
+        else
+
+          define_group_ranks
+          
+          if @group_ranks[@group] > @group_ranks[@ssn_high_group_code.group]
+            @errors << "Group '#{@group}' has not been assigned yet for area '#{@area}'"
+          end
+        end
+      end
+
+
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+
+    private
+
+    def define_group_ranks
+      @group_ranks = {}
+      rank = 0
+      (1..9).step(2) do |group|
+        @group_ranks.merge!("0#{group.to_s}" => rank += 1)
+      end
+      (10..98).step(2) do |group|
+        @group_ranks.merge!(group.to_s => rank += 1)
+      end
+      (2..8).step(2) do |group|
+        @group_ranks.merge!("0#{group.to_s}" => rank += 1)
+      end
+      (11..99).step(2) do |group|
+        @group_ranks.merge!(group.to_s => rank += 1)
+      end
+    end
+  end
+end

data/lib/ssn_validator.rb

@@ -0,0 +1,13 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+  
+require 'ssn_validator/models/ssn_high_group_code'
+require 'ssn_validator/models/ssn_validator'
+require 'rake'
+
+# Load rake file
+import "#{File.dirname(__FILE__)}/tasks/ssn_validator.rake"
+
+module SsnValidator
+  VERSION = '0.1.1'
+end

data/lib/tasks/ssn_validator.rake

@@ -0,0 +1,8 @@
+
+namespace :ssn_validator do
+  desc "Loads the current file from http://www.socialsecurity.gov/employer/ssns/highgroup.txt if it hasn't already been loaded."
+  task :update_data => :environment do
+    puts SsnHighGroupCode.load_current_high_group_codes_file
+  end
+  
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/ssn_validator.rb'}"
+puts "Loading ssn_validator gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/test/test_helper.rb

@@ -0,0 +1,26 @@
+require 'stringio'
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/ssn_validator'
+
+ActiveRecord::Base.establish_connection :adapter => 'sqlite3', :database => ':memory:'
+
+def create_ssn_high_group_codes_table
+  silence_stream(STDOUT) do
+    ActiveRecord::Schema.define(:version => 1) do
+      create_table :ssn_high_group_codes do |t|
+        t.date      :as_of
+        t.string    :area
+        t.string    :group
+        t.timestamps
+      end
+
+      add_index :ssn_high_group_codes, [:area]
+      add_index :ssn_high_group_codes, [:area, :as_of]
+    end
+  end
+end
+
+def setup_high_group_codes_table
+	ActiveRecord::Base.connection.tables.each { |table| ActiveRecord::Base.connection.drop_table(table) }
+  create_ssn_high_group_codes_table
+end

data/test/test_ssn_high_group_code.rb

@@ -0,0 +1,22 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class TestSsnHighGroupCode < Test::Unit::TestCase
+
+  def setup
+    setup_high_group_codes_table
+  end
+  
+  def test_should_load_table_with_current_file
+    assert_equal(0,SsnHighGroupCode.count)
+    SsnHighGroupCode.load_current_high_group_codes_file
+    assert SsnHighGroupCode.count > 0
+  end
+
+  def test_should_not_load_table_if_as_of_already_in_table
+    SsnHighGroupCode.load_current_high_group_codes_file
+    assert SsnHighGroupCode.count > 0
+    record_count = SsnHighGroupCode.count
+    SsnHighGroupCode.load_current_high_group_codes_file
+    assert_equal(record_count, SsnHighGroupCode.count)
+  end
+end

data/test/test_ssn_validator.rb

@@ -0,0 +1,65 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class TestSsnValidator < Test::Unit::TestCase
+
+  KNOWN_DUMMY_SSNS = %w(078051120 111111111 123456789 219099999 999999999)
+  MISSPLACED_HYPHEN_SSNS = %w(1-2-3456789 12-345678-9 123-4-56789 123-456789 1234567-89 12-345-6789 12345-6789 1234-5-6789)
+  INVALID_LENGTH_SSNS = %w(1 12 123 1234 12345 123456 1234567 13245678 1234567890)
+  NONDIGIT_SSNS = %w(078051a20 078F51120 78051#20 051,20 078051m20)
+  INVALID_ZEROS_SSNS = %w(166-00-1234 073-96-0000)
+  GROUPS_NOT_ASSIGNED_TO_AREA_SSNS = %w(752991234 755971234 762991254)
+
+  VALID_SSNS = %w(001021234 161-84-9876 223981111)
+  VALID_INTEGER_SSNS = [115941234, 161849876, 223981111]
+  
+  def setup
+    setup_high_group_codes_table
+    SsnHighGroupCode.load_current_high_group_codes_file
+  end
+  
+  def test_ssn_validations
+    KNOWN_DUMMY_SSNS.each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert !validator.valid?
+      assert validator.errors.include?('Known dummy SSN.'), "Errors: #{validator.errors}"
+    end
+
+    MISSPLACED_HYPHEN_SSNS.each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert !validator.valid?
+      assert validator.errors.include?('Hyphen misplaced.'), "Errors: #{validator.errors}"
+    end
+
+    INVALID_LENGTH_SSNS.each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert !validator.valid?
+      assert validator.errors.include?('SSN not 9 digits long.'), "Errors: #{validator.errors}"
+    end
+
+    NONDIGIT_SSNS.each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert !validator.valid?
+      assert validator.errors.include?('Non-digit found.'), "Errors: #{validator.errors}"
+    end
+
+    INVALID_ZEROS_SSNS.each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert !validator.valid?
+      assert validator.errors.include?('Invalid group or serial number.'), "Errors: #{validator.errors}"
+    end
+
+    GROUPS_NOT_ASSIGNED_TO_AREA_SSNS.each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert !validator.valid?
+      assert validator.errors.include?("Group '#{validator.group}' has not been assigned yet for area '#{validator.area}'"), "Errors: #{validator.errors}"
+    end
+    
+    (VALID_SSNS + VALID_INTEGER_SSNS).each do |ssn|
+      validator = SsnValidator::Ssn.new(ssn)
+      assert validator.valid?, "Errors: #{validator.errors}"
+    end
+
+
+  end
+
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: kevintyll-ssn_validator
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Kevin Tyll
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-13 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 2.0.0
+    version: 
+description: 
+email: kevintyll@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+- Rakefile
+- generators/ssn_validator_migration/templates/migration.rb
+- generators/ssn_validator_migration/ssn_validator_migration_generator.rb
+- lib/ssn_validator/models/ssn_high_group_code.rb
+- lib/ssn_validator/models/ssn_validator.rb
+- lib/ssn_validator.rb
+- lib/tasks/ssn_validator.rake
+- script/console
+- script/destroy
+- script/generate
+- test/test_helper.rb
+- test/test_ssn_validator.rb
+- test/test_ssn_high_group_code.rb
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- .
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Validates whether an SSN has likely been issued or not.
+test_files: 
+- test/test_helper.rb
+- test/test_ssn_validator.rb
+- test/test_ssn_high_group_code.rb