identified 0.1.0

data/data/ssn/high_groups/september_2009_raw.txt

@@ -0,0 +1,141 @@
+
+	HIGHEST GROUP ISSUED AS OF 06/24/11
+
+Anything with an asterisk(*) is a change effective 06/24/11.
+This list shows the SSN area and group numbers that are in
+the process of being issued as of the date at the top of this page.
+
+NOTE: * INDICATES GROUP CHANGE SINCE LAST MONTH.
+
+001 11 	002 11	003 08	004 13	005 13*	006 11
+007 11	008 94	009 94* 010 94	011 94 	012 94 
+013 94	014 94	015 94	016 94 	017 94	018 94
+019 94	020 94	021 94*	022 92	023 92	024 92
+025 92	026 92	027 92	028 92	029 92	030 92
+031 92	032 92	033 92	034 92	035 74	036 74
+037 74 	038 74	039 74	040 15	041 15 	042 15
+043 15	044 15	045 15	046 15	047 15	048 15 
+049 15*	050 02	051 02	052 02	053 02	054 02
+055 02	056 02	057 02	058 02	059 02	060 02 
+061 02	062 02	063 02	064 02	065 02	066 02
+067 02	068 02 	069 02 	070 02 	071 02	072 02
+073 02	074 02	075 02	076 02	077 02	078 02
+079 02	080 02	081 02	082 02 	083 02 	084 02 
+085 02 	086 02	087 02	088 02	089 02	090 02
+091 02	092 02	093 02	094 02	095 02	096 02
+097 02	098 02	099 02	100 02	101 02	102 02
+103 02*	104 02*	105 02*	106 98	107 98	108 98
+109 98	110 98	111 98	112 98	113 98  114 98 
+115 98  116 98  117 98 	118 98 	119 98	120 98
+121 98	122 98	123 98	124 98	125 98	126 98 
+127 98  128 98	129 98	130 98	131 98	132 98
+133 98	134 98	135 25	136 25	137 25	138 25*
+139 23	140 23	141 23	142 23 	143 23	144 23 
+145 23	146 23	147 23	148 23 	149 23	150 23
+151 23	152 23	153 23 	154 23  155 23	156 23
+157 23	158 23	159 86	160 86	161 86	162 86
+163 86	164 86	165 86	166 86	167 86	168 86			
+169 86	170 86	171 86	172 86	173 86	174 86
+175 86	176 86	177 86	178 86	179 86	180 86  
+181 86  182 86  183 86	184 86	185 86	186 86
+187 86 	188 86	189 86	190 86	191 86	192 86
+193 86	194 86	195 86* 196 84	197 84	198 84
+199 84	200 84	201 84	202 84	203 84	204 84
+205 84	206 84	207 84	208 84	209 84	210 84
+211 84	212 91	213 91	214 91	215 91*	216 89 
+217 89 	218 89	219 89	220 89	221 13	222 11
+223 99	224 99  225 99  226 99  227 99	228 99	
+229 99	230 99	231 99	232 57	233 57	234 57 
+235 57*	236 55	237 99	238 99	239 99	240 99
+241 99	242 99	243 99  244 99  245 99	246 99
+247 99	248 99	249 99	250 99	251 99	252 99
+253 99	254 99	255 99	256 99	257 99	258 99
+259 99	260 99	261 99	262 99	263 99	264 99
+265 99	266 99	267 99	268 17	269 17	270 17 
+271 17 	272 17	273 17	274 17	275 17	276 17
+277 17	278 17*	279 15	280 15	281 15	282 15
+283 15	284 15	285 15	286 15  287 15	288 15
+289 15	290 15	291 15	292 15	293 15	294 15
+295 15	296 15	297 15	298 15	299 15	300 15 
+301 15	302 15	303 37 	304 37	305 37	306 37 
+307 37	308 37	309 37	310 37	311 35	312 35
+313 35	314 35  315 35	316 35	317 35	318 11
+319 11	320 11	321 11	322 11	323 11	324 11
+325 11	326 11	327 11	328 11 	329 11 	330 11 
+331 11	332 11	333 11	334 11	335 11 	336 11 
+337 11	338 11	339 11  340 11	341 11	342 11
+343 11	344 11	345 11*	346 08	347 08	348 08
+349 08	350 08	351 08	352 08	353 08	354 08
+355 08	356 08	357 08	358 08	359 08	360 08
+361 08	362 39	363 39 	364 39	365 39	366 39
+367 39	368 39	369 39*	370 37	371 37	372 37
+373 37	374 37	375 37	376 37	377 37	378 37 
+379 37	380 37	381 37	382 37	383 37 	384 37
+385 37	386 37  387 33  388 33	389 33	390 33
+391 33 	392 33	393 33 	394 33 	395 33	396 33
+397 33	398 31	399 31	400 73 	401 73	402 73   
+403 73	404 73	405 73	406 73	407 73	408 99
+409 99	410 99	411 99  412 99	413 99	414 99
+415 99	416 67	417 67	418 67	419 67	420 67
+421 67	422 67	423 67	424 65	425 99	426 99
+427 99	428 99	429 99	430 99	431 99	432 99
+433 99	434 99	435 99	436 99	437 99	438 99
+439 99  440 29	441 29	442 29*	443 27	444 27
+445 27	446 27 	447 27	448 27 	449 99	450 99
+451 99	452 99	453 99	454 99	455 99	456 99
+457 99	458 99	459 99	460 99	461 99	462 99
+463 99	464 99	465 99	466 99	467 99	468 57 
+469 57	470 57  471 57	472 57*	473 55	474 55
+475 55	476 55	477 55	478 43*	479 41	480 41
+481 41 	482 41	483 41	484 41 	485 41	486 29
+487 29	488 29	489 29	490 29	491 29	492 29
+493 29 	494 29	495 29	496 29 	497 29	498 29
+499 29 	500 29*	501 37	502 37	503 45 	504 45 
+505 59	506 57	507 57	508 57	509 33	510 33 
+511 33	512 33*	513 31 	514 31	515 31	516 49
+517 49	518 89	519 87  520 61	521 99	522 99
+523 99	524 99	525 99	526 99	527 99	528 99
+529 99	530 99	531 71	532 71	533 71 	534 71
+535 71	536 71	537 71	538 71	539 71*	540 83 
+541 83*	542 81	543 81	544 81	545 99	546 99
+547 99	548 99	549 99	550 99	551 99	552 99
+553 99	554 99	555 99	556 99	557 99	558 99
+559 99	560 99	561 99	562 99	563 99	564 99
+565 99	566 99	567 99	568 99	569 99	570 99
+571 99	572 99	573 99	574 61	575 99	576 99
+577 53	578 53	579 53	580 41*	581 99	582 99
+583 99	584 99	585 99	586 67	587 99  588 09
+589 99  590 99	591 99	592 99	593 99  594 99  
+595 99  596 94*	597 92	598 92	599 92 	600 99	
+601 99  602 87	603 87	604 87	605 87	606 87 
+607 87  608 87	609 87	610 87	611 87	612 87 	
+613 87	614 87	615 87*	616 87*	617 87*	618 87*	
+619 87*	620 85	621 85	622 85	623 85	624 85 	
+625 85	626 85	627 31	628 31	629 31	630 31 	
+631 31	632 31	633 31	634 31*	635 31*	636 31*	
+637 29	638 29	639 29	640 29	641 29	642 29
+643 29	644 29	645 29	646 23	647 21	648 58	
+649 56	650 62 	651 62	652 62	653 60	654 38 	
+655 36	656 36	657 36	658 36	659 24	660 24*  
+661 22  662 22	663 22  664 22	665 22	667 48  
+668 48 	669 48	670 48	671 48	672 48	673 48	
+674 48  675 48*	676 22 	677 22	678 22* 679 20
+680 31	681 24	682 24 	683 24	684 24	685 24 	
+686 24	687 24	688 24	689 24*	690 22	691 18   
+692 18*	693 16	694 16	695 16  696 16	697 16 
+698 16	699 16	700 18	701 18  702 18  703 18  
+704 18  705 18  706 18	707 18  708 18  709 18  
+710 18  711 18	712 18	713 18  714 18  715 18  
+716 18  717 18	718 18	719 18  720 18  721 18  
+722 18  723 18	724 28	725 18  726 18  727 10	
+728 14  729 28	730 28	731 28	732 28*	733 26	
+750 20	751 18	752 09  753 07 	754 07	755 07 
+756 12  757 12	758 12	759 12  760 12	761 12	
+762 12	763 12	764 29*	765 27	766 04* 767 02 
+768 02	769 02	770 02	771 02	772 02* 	
+  
+
+ 
+
+ 
+

data/data/ssn/high_groups/september_2010_raw.txt

@@ -0,0 +1,141 @@
+
+	HIGHEST GROUP ISSUED AS OF 09/01/10
+
+Anything with an asterisk(*) is a change effective 09/01/10.
+This list shows the SSN area and group numbers that are in
+the process of being issued as of the date at the top of this page.
+
+NOTE: * INDICATES GROUP CHANGE SINCE LAST MONTH.
+
+001 11 	002 08	003 08	004 11	005 11	006 11
+007 11	008 94	009 92  010 94	011 94 	012 94*
+013 92	014 92	015 92	016 92	017 92	018 92
+019 92	020 92	021 92	022 92	023 92	024 92
+025 92	026 92	027 92	028 92	029 92	030 92
+031 92	032 92	033 92	034 92	035 74	036 74
+037 74 	038 74	039 72	040 15	041 15 	042 15
+043 15	044 15	045 13	046 13	047 13	048 13 
+049 13	050 02	051 02	052 02	053 02	054 02
+055 02	056 02	057 02	058 02	059 02	060 02 
+061 02	062 02	063 02	064 02	065 02	066 02
+067 02	068 02*	069 02*	070 02*	071 98	072 98
+073 98	074 98	075 98	076 98	077 98	078 98
+079 98	080 98	081 98	082 98	083 98	084 98
+085 98	086 98	087 98	088 98	089 98	090 98
+091 98	092 98	093 98	094 98	095 98	096 98
+097 98	098 98	099 98	100 98	101 98	102 98
+103 98	104 98	105 98	106 98	107 98	108 98
+109 98	110 98	111 98	112 98	113 98  114 98 
+115 98  116 98  117 98 	118 98 	119 98	120 98
+121 98	122 98	123 98	124 98	125 98	126 98 
+127 98  128 98	129 98	130 98	131 98	132 98
+133 98	134 98	135 23	136 23	137 23	138 23
+139 23	140 23	141 23	142 23 	143 23	144 23 
+145 23	146 23	147 23	148 23*	149 21	150 21
+151 21	152 21	153 21	154 21  155 21	156 21
+157 21	158 21	159 86	160 86	161 86	162 86
+163 86	164 86	165 86	166 86	167 86	168 86			
+169 86	170 86	171 86	172 86	173 86	174 86
+175 86	176 86	177 86	178 86	179 86	180 86* 
+181 86* 182 84	183 84	184 84	185 84	186 84
+187 84	188 84	189 84	190 84	191 84	192 84
+193 84	194 84	195 84  196 84	197 84	198 84
+199 84	200 84	201 84	202 84	203 84	204 84
+205 84	206 84	207 84	208 84	209 84	210 84
+211 84	212 89	213 89*	214 87	215 87	216 87 
+217 87	218 87	219 87	220 87	221 11	222 11
+223 99	224 99  225 99  226 99  227 99	228 99	
+229 99	230 99	231 99	232 57	233 57	234 55
+235 55	236 55	237 99	238 99	239 99	240 99
+241 99	242 99	243 99  244 99  245 99	246 99
+247 99	248 99	249 99	250 99	251 99	252 99
+253 99	254 99	255 99	256 99	257 99	258 99
+259 99	260 99	261 99	262 99	263 99	264 99
+265 99	266 99	267 99	268 15	269 15	270 15
+271 15	272 15	273 15	274 15	275 15	276 15
+277 15	278 15	279 15	280 15	281 15	282 15
+283 15	284 15	285 15	286 15  287 15	288 15
+289 15	290 15	291 15	292 15	293 15	294 15
+295 15	296 15	297 15	298 15	299 15	300 15*
+301 13	302 13	303 37*	304 35	305 35	306 35
+307 35	308 35	309 35	310 35	311 35	312 35
+313 35	314 35  315 35	316 35	317 35	318 11
+319 11	320 11	321 11	322 11	323 11	324 11
+325 11	326 11	327 11	328 11*	329 11*	330 08 
+331 08	332 08	333 08	334 08 	335 08 	336 08
+337 08	338 08	339 08	340 08	341 08	342 08
+343 08	344 08	345 08	346 08	347 08	348 08
+349 08	350 08	351 08	352 08	353 08	354 08
+355 08	356 08	357 08	358 08	359 08	360 08
+361 08	362 37	363 37	364 37	365 37	366 37
+367 37	368 37	369 37	370 37	371 37	372 37
+373 37	374 37	375 37	376 37	377 37	378 37 
+379 37	380 37	381 37	382 37	383 37*	384 35
+385 35	386 35  387 33	388 33	389 33	390 33
+391 33*	392 31	393 31  394 31	395 31	396 31
+397 31	398 31	399 31	400 73 	401 73	402 73*  
+403 71	404 71	405 71	406 71	407 71	408 99
+409 99	410 99	411 99  412 99	413 99	414 99
+415 99	416 67	417 67	418 67	419 65	420 65
+421 65	422 65	423 65	424 65	425 99	426 99
+427 99	428 99	429 99	430 99	431 99	432 99
+433 99	434 99	435 99	436 99	437 99	438 99
+439 99  440 27	441 27	442 27	443 27	444 27
+445 27	446 27*	447 25	448 25	449 99	450 99
+451 99	452 99	453 99	454 99	455 99	456 99
+457 99	458 99	459 99	460 99	461 99	462 99
+463 99	464 99	465 99	466 99	467 99	468 55
+469 55	470 55	471 55 	472 55	473 55	474 55
+475 55	476 53	477 53	478 41	479 41	480 41
+481 41 	482 41	483 39	484 39	485 39	486 29
+487 29	488 29	489 29	490 29	491 29	492 29
+493 29*	494 27	495 27	496 27	497 27	498 27
+499 27  500 27	501 37	502 35	503 45 	504 43 
+505 57	506 57	507 55	508 55	509 31	510 31
+511 31	512 31	513 31 	514 31	515 31	516 49
+517 47	518 87*	519 85  520 61	521 99	522 99
+523 99	524 99	525 99	526 99	527 99	528 99
+529 99	530 99	531 69	532 69	533 69 	534 69
+535 69 	536 69	537 69	538 69*	539 67	540 81 
+541 81 	542 79	543 79	544 79 	545 99	546 99
+547 99	548 99	549 99	550 99	551 99	552 99
+553 99	554 99	555 99	556 99	557 99	558 99
+559 99	560 99	561 99	562 99	563 99	564 99
+565 99	566 99	567 99	568 99	569 99	570 99
+571 99	572 99	573 99	574 59	575 99	576 99
+577 51	578 51	579 51	580 39	581 99	582 99
+583 99	584 99	585 99	586 65	587 99  588 07
+589 99  590 99	591 99	592 99	593 99  594 99  
+595 99  596 92*	597 90	598 90	599 90	600 99	
+601 99  602 83	603 83	604 83	605 83	606 83
+607 83* 608 83*	609 83*	610 83*	611 83*	612 83*	
+613 83*	614 81	615 81	616 81	617 81	618 81	
+619 81 	620 81	621 81	622 81	623 81	624 81 	
+625 81 	626 81	627 27	628 27  629 27	630 27	
+631 27	632 27*	633 27*	634 27*	635 27*	636 25	
+637 25 	638 25	639 25	640 25	641 25	642 25
+643 25	644 25	645 25	646 17 	647 17	648 54	
+649 54	650 60* 651 58	652 58	653 58	654 36*	
+655 34	656 34	657 34	658 34	659 22 	660 22  
+661 22* 662 20 	663 20  664 20	665 20	667 46  
+668 46 	669 46	670 46	671 46*	672 44	673 44	
+674 44  675 44 	676 20	677 20	678 20  679 18
+680 25*	681 22 	682 22	683 22	684 22	685 22 	
+686 22*	687 20	688 20	689 20 	690 20	691 16*  
+692 14	693 14	694 14 	695 14  696 14	697 14 
+698 14 	699 14	700 18	701 18  702 18  703 18  
+704 18  705 18  706 18	707 18  708 18  709 18  
+710 18  711 18	712 18	713 18  714 18  715 18  
+716 18  717 18	718 18	719 18  720 18  721 18  
+722 18  723 18	724 28	725 18  726 18  727 10	
+728 14  729 24	730 24* 731 24*	732 22	733 22	
+750 18*	751 16	752 07  753 07 	754 05	755 05
+756 12* 757 10	758 10 	759 10  760 10	761 10	
+762 10 	763 10	764 19	765 19*	766 94*	767 94*
+768 94*	769 92	770 92	771 92	772 92	
+  
+
+ 
+
+ 
+

data/lib/identified.rb

@@ -0,0 +1,24 @@
+require 'date'
+require 'delegate'
+
+require_relative 'identified/errors/error'
+require_relative 'identified/errors/ssn/malformed_ssn_error'
+
+require_relative 'identified/ssn/area_number'
+require_relative 'identified/ssn/group_number'
+require_relative 'identified/ssn/sequential_group_number'
+require_relative 'identified/ssn/serial_number'
+require_relative 'identified/ssn/high_group_list'
+require_relative 'identified/ssn/high_group_data'
+require_relative 'identified/ssn/issuing_state_data'
+require_relative 'identified/ssn/ssn'
+
+# A module for validating government document identifiers (like SSNs) with ease.
+module Identified
+  # Config information commonly useful to all other modules & classes
+  module Config
+    def self.data_path
+      File.expand_path(File.join(__FILE__, '../../data/'))
+    end
+  end
+end

data/lib/identified/errors/error.rb

@@ -0,0 +1,5 @@
+module Identified
+  # Common error class for the Identified module.
+  class Error < StandardError
+  end
+end

data/lib/identified/errors/ssn/malformed_ssn_error.rb

@@ -0,0 +1,5 @@
+module Identified
+  # Raised when ssns aren't in the '123-45-6789' or '123456789' formats.
+  class MalformedSSNError < Error
+  end
+end

data/lib/identified/ssn/area_number.rb

@@ -0,0 +1,15 @@
+module Identified
+  # Represents the area number of an SSN. 
+  class AreaNumber < DelegateClass(Fixnum)
+    # Returns whether the ssn COULD be a valid ssn area code.
+    def valid?
+      # Currently only 000, 666 & 900+ are prohibited area numbers.
+      # See http://www.ssa.gov/employer/randomization.html
+      (1..665).include?(self) || (667..899).include?(self)
+
+      # NOTE: Prior to randomization, there were more restricted ranges. This is no longer checked
+      # inside of AreaNumber because it is redundant due to the pre-randomization group number check
+      # also validating this same information (if the area is absent in the table, it is unissued).
+    end
+  end
+end

data/lib/identified/ssn/group_number.rb

@@ -0,0 +1,27 @@
+module Identified
+  # Represents the group number of an SSN and performs group number validation.
+  class GroupNumber < DelegateClass(Fixnum)
+    # Returns whether the ssn COULD be a valid ssn group code.
+    def valid?(area = nil, date_issued = nil)
+      # When no date is provided, we assume the date issued is post randomization.
+      if !date_issued || date_issued >= SSN::RANDOMIZATION_DATE
+        (1..99).include?(self)
+      else
+        (1..99).include?(self) && valid_high_group?(area, date_issued)
+      end
+    end
+
+    private
+
+    # Helper function to determine if the group number was valid in a given area on a given date.
+    def valid_high_group?(area, date_issued)
+      high_group_list = HighGroupData.latest_applicable_list(date_issued)
+      high_group = high_group_list.high_group(area)
+
+      # If no groups have been issued yet for this area, the group is not valid.
+      return false unless high_group
+
+      SequentialGroupNumber.new(self) <= SequentialGroupNumber.new(high_group)
+    end
+  end
+end

data/lib/identified/ssn/high_group_data.rb

@@ -0,0 +1,27 @@
+module Identified
+  # The module that provides access to set of all high group data available.
+  module HighGroupData
+    def self.all
+      data
+    end
+
+    # Fetch the earliest dated list that is on or later than the issuance date.
+    def self.latest_applicable_list(date_issued)
+      data.detect { |list| date_issued <= list.date_effective }
+    end
+
+    def self.data
+      @data ||= load_data
+    end
+    private_class_method :data
+
+    # Loads all high group lists into memory. The data is sorted in increasing order by the date the
+    # high group list was effective on.
+    def self.load_data
+      Dir[Config.data_path + '/ssn/high_groups/*.txt']
+        .map { |filename| HighGroupList.new(filename) }
+        .sort_by!(&:date_effective)
+    end
+    private_class_method :load_data
+  end
+end

data/lib/identified/ssn/high_group_list.rb

@@ -0,0 +1,48 @@
+module Identified
+  # An in-memory representation of a textual high group list.
+  class HighGroupList
+    HIGH_GROUP_LIST_DATE_REGEX = %r(HIGHEST GROUP ISSUED AS OF (?<date>\d{1,2}/\d{2}/\d{2}))
+
+    attr_reader :date_effective, :high_groups
+
+    def initialize(filename)
+      raw_data = File.read(filename)
+
+      @date_effective = parse_date(raw_data)
+      @high_groups = parse_high_groups(raw_data)
+    end
+
+    def high_group(area)
+      high_groups[area] # Returns nil if area is not present!
+    end
+
+    private
+
+    # Searches the raw for the effective date.
+    def parse_date(raw_data)
+      raw_date = HIGH_GROUP_LIST_DATE_REGEX.match(raw_data)[:date]
+
+      day, month, year = extract_date_elements(raw_date)
+
+      Date.new(year, month, day)
+    end
+
+    # Helper function to extract the integer components from the raw date string.
+    def extract_date_elements(date_string)
+      date_parts = date_string.split('/')
+
+      year = date_parts.fetch(2).to_i + 2000
+      month = date_parts.fetch(0).to_i
+      day = date_parts.fetch(1).to_i
+
+      [day, month, year]
+    end
+
+    # Loads high groups into a hash table that is indexed by area.
+    def parse_high_groups(raw_data)
+      raw_data.scan(/(\d{3})\s+(\d{2})/).to_enum.with_object({}) do |(area, group), table|
+        table[area.to_i] = group.to_i
+      end
+    end
+  end
+end

data/lib/identified/ssn/issuing_state_data.rb

@@ -0,0 +1,44 @@
+module Identified
+  # Wraps the actual data file to provide convenient access to area number => issuing state info.
+  module IssuingStateData
+    ISSUING_STATE_ENTRY_REGEX = /(\d{3})-(\d{3})\s(\w{2})/
+    # Provides an array of potential states or protectorates the ssn was issued in. Date is required
+    # because this information cannot be known if it was issued after the randomizaiton date.
+    # Unknown area numbers return [].
+    def self.issuing_states(area_number, date_issued)
+      # When the date issued is after the randomization date, we have no information about the
+      # issuing area, so return [].
+      return [] if !date_issued || date_issued >= SSN::RANDOMIZATION_DATE
+
+      @issuing_areas_table ||= load_issuing_states_table
+
+      # Return [] if the issuing areas information doesn't cover the requested area.
+      @issuing_areas_table.fetch(area_number, [])
+    end
+
+    # Loads the lookup table for going from area # => state / province code
+    def self.load_issuing_states_table
+      # Data originally taken from http://www.socialsecurity.gov/employer/stateweb.htm. The file
+      # this reads was transformed slightly from the original to make it less cumbersome to parse.
+      raw_data = File.read(File.join(Config.data_path, 'ssn/area_data.txt'))
+
+      # issuing_states_table = parse_issuing_states(raw_data)
+      parse_issuing_states(raw_data)
+    end
+
+    # Parses the issuing areas file contents and converts the data into a lookup table.
+    def self.parse_issuing_states(raw_data)
+      lookup_table = {}
+
+      # The data is formatted as a range [start]-[end] then the two character state / province code.
+      raw_data.scan(ISSUING_STATE_ENTRY_REGEX) do |start_area, end_area, state_code|
+        (start_area.to_i).upto(end_area.to_i) do |area_number|
+          lookup_table[area_number] ||= []
+          lookup_table.fetch(area_number) << state_code
+        end
+      end
+
+      lookup_table
+    end
+  end
+end