gov_codes 0.1.0 → 0.1.1

data/lib/gov_codes/afsc/ri.rb

@@ -0,0 +1,172 @@
+require "strscan"
+require "yaml"
+require_relative "../data_loader"
+
+module GovCodes
+  module AFSC
+    # Reporting Identifiers (RI) and Special Duty Identifiers (SDI)
+    # These codes follow a different format than standard AFSCs:
+    # - Career field: digit + letter (e.g., "9Z", "8A")
+    # - Identifier: 3 digits (e.g., "200", "400")
+    # - Optional suffix: letter (e.g., "A", "B")
+    #
+    # Examples: 9Z200, 8A400, 8G000B, 8R300A
+    module RI
+      class Parser
+        def initialize(code)
+          @code = code
+        end
+
+        def parse
+          scanner = StringScanner.new(@code.to_s)
+          result = {
+            career_group: nil,
+            career_field: nil,
+            identifier: nil,
+            suffix: nil,
+            specific_ri: nil
+          }
+
+          # Scan for career group (single digit)
+          career_group = scanner.scan(/\d/)
+          return result unless career_group
+          result[:career_group] = career_group.to_sym
+
+          # Scan for career field letter
+          career_field_letter = scanner.scan(/[A-Z]/)
+          return result unless career_field_letter
+          result[:career_field] = :"#{career_group}#{career_field_letter}"
+
+          # Scan for identifier (3 digits)
+          identifier = scanner.scan(/\d{3}/)
+          return result unless identifier
+          result[:identifier] = identifier.to_sym
+
+          # Build specific RI code
+          result[:specific_ri] = :"#{result[:career_field]}#{identifier}"
+
+          # Scan for optional suffix (letter)
+          suffix = scanner.scan(/[A-Z]/)
+          result[:suffix] = suffix&.to_sym
+
+          # Check if we've reached the end of the string
+          return result unless scanner.eos?
+
+          result
+        end
+      end
+
+      extend GovCodes::DataLoader
+
+      DATA = data
+
+      Code = Data.define(
+        :career_group,
+        :career_field,
+        :identifier,
+        :suffix,
+        :specific_ri,
+        :name
+      )
+
+      def self.find_name_recursive(result)
+        name = nil
+        data = DATA
+
+        career_field = result[:career_field]
+        identifier = result[:identifier]
+        suffix = result[:suffix]
+
+        # Look for the career field (e.g., "9Z", "8A")
+        if data[career_field]
+          field_data = data[career_field]
+
+          # Career field has name and subcategories
+          if field_data.is_a?(Hash) && field_data[:subcategories]
+            subcats = field_data[:subcategories]
+
+            # Look for the identifier (e.g., "200", "400")
+            if subcats[identifier]
+              identifier_data = subcats[identifier]
+
+              if identifier_data.is_a?(Hash)
+                name = identifier_data[:name]
+
+                # Look for suffix if present
+                if suffix && identifier_data[:subcategories]
+                  suffix_data = identifier_data[:subcategories][suffix]
+                  name = suffix_data if suffix_data.is_a?(String)
+                  name = suffix_data[:name] if suffix_data.is_a?(Hash)
+                end
+              else
+                # Simple string value
+                name = identifier_data
+              end
+            end
+          end
+        end
+
+        name || "Unknown"
+      end
+
+      def self.find(code)
+        code = code.to_s
+        CODES[code] ||= begin
+          parser = Parser.new(code)
+          result = parser.parse
+
+          # Return nil if parsing failed or required fields are missing
+          return nil if result.reject { |_, v| v.nil? }.empty? ||
+            result[:career_group].nil? ||
+            result[:career_field].nil? ||
+            result[:identifier].nil? ||
+            result[:specific_ri].nil?
+
+          # Find the name by recursively searching the codes hash
+          name = find_name_recursive(result)
+
+          # Return nil if name is "Unknown" (code not in data)
+          return nil if name == "Unknown"
+
+          # Add the name to the result
+          result[:name] = name
+
+          Code.new(**result)
+        end
+      end
+
+      def self.reset_data(lookup: $LOAD_PATH)
+        remove_const(:DATA) if const_defined?(:DATA)
+        const_set(:DATA, data(lookup:))
+        CODES.clear
+      end
+
+      def self.search(prefix)
+        results = []
+        prefix = prefix.to_s.upcase
+        collect_codes_recursive(DATA, "", prefix, results)
+        results.map { |code| find(code) }.compact
+      end
+
+      def self.collect_codes_recursive(data, current_code, prefix, results)
+        return unless data.is_a?(Hash)
+
+        data.each do |key, value|
+          code = "#{current_code}#{key}"
+
+          if value.is_a?(Hash) && value[:name]
+            # This is a node with a name and possibly subcategories
+            results << code if code.start_with?(prefix)
+            collect_codes_recursive(value[:subcategories], code, prefix, results) if value[:subcategories]
+          elsif value.is_a?(String)
+            # This is a leaf node (simple string value)
+            results << code if code.start_with?(prefix)
+          elsif value.is_a?(Hash)
+            # Nested subcategories without a name at this level
+            collect_codes_recursive(value, current_code, prefix, results)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gov_codes/afsc/ri.yml

@@ -0,0 +1,237 @@
+# Reporting Identifiers (RI) and Special Duty Identifiers (SDI)
+# Source: https://en.wikipedia.org/wiki/Air_Force_Specialty_Code
+# Wikipedia Revision: 1318430021
+# Extracted: 2025-11-17
+#
+# IMPORTANT: This file contains ONLY codes explicitly listed on Wikipedia.
+# No predictions, no assumptions, no hallucinations.
+# See .agent-os/product/decisions.md (DEC-003) for anti-hallucination policy.
+#
+# Format: Career field (digit + letter) + identifier (3 digits) + optional suffix
+# Examples: 8A400, 9Z200, 8G000B, 8R300A
+
+:8A:
+  :name: Enlisted aide and protocol
+  :subcategories:
+    :200: Enlisted aide
+    :300: Protocol
+    :400: Talent management consultant
+:8B:
+  :name: Military training
+  :subcategories:
+    :000: Military training instructor
+    :100: Military Training leader
+    :200: Academy military training NCO
+    :300: Officer accessions instructor
+:8C:
+  :name: Military and family readiness
+  :subcategories:
+    :000: Military and family readiness non-commissioned officer (RNCO)
+:8D:
+  :name: Language and culture
+  :subcategories:
+    :100: Language & culture advisor
+:8F:
+  :name: First sergeant
+  :subcategories:
+    :000: First sergeant
+:8G:
+  :name: Honor guard
+  :subcategories:
+    :000:
+      :name: Premier honor guard
+      :subcategories:
+        :B: Pallbearer
+        :C: Color guard
+        :D: Drill team
+    :100: Base honor guard program manager
+:8H:
+  :name: Airmen dorm leader
+  :subcategories:
+    :000: Airmen dorm leader
+:8I:
+  :name: Inspector general
+  :subcategories:
+    :000: Superintendent, inspector general
+    :100: Inspections coordinator
+    :200: Complaints & resolution coordinator
+:8K:
+  :name: Software development
+  :subcategories:
+    :000: Software development specialist
+:8L:
+  :name: Air advisor
+  :subcategories:
+    :100: Air advisor basic
+    :200: Air advisor basic, team sergeant
+    :300: Air advisor basic, team leader
+    :400: Air advisor advanced
+    :500: Air advisor advanced, team sergeant
+    :600: Air advisor advanced, team leader
+    :700: Combat aviation advisor
+    :800: Combat aviation advisor team sergeant
+    :900: Combat aviation advisor team leader
+:8P:
+  :name: Courier and defense attaché
+  :subcategories:
+    :000: Courier
+    :100: Defense attaché
+:8R:
+  :name: Recruiting
+  :subcategories:
+    :000: Enlisted accessions recruiter
+    :200: Second-tier recruiter
+    :300:
+      :name: Third-tier recruiter
+      :subcategories:
+        :A: Flight chief
+        :B: Graduated, flight chief
+        :C: Production superintendent
+        :E: Senior enlisted leader
+:8S:
+  :name: Missile facility
+  :subcategories:
+    :000: Missile facility manager
+    :200: Combat crew communications
+:8T:
+  :name: Professional military education
+  :subcategories:
+    :000: Professional military education instructor
+    :100: Enlisted professional military education instructional system designer
+    :200: Development advisor
+:8U:
+  :name: Unit deployment
+  :subcategories:
+    :000: Unit deployment manager
+    :100: Weapons of mass destruction civil support team (WMD-CST)
+:8W:
+  :name: Weapons safety
+  :subcategories:
+    :000: Weapons safety manager – wing level
+:8Y:
+  :name: Pathfinder
+  :subcategories:
+    :000: Pathfinder
+:9A:
+  :name: Disqualified/awaiting separation
+  :subcategories:
+    :000: Enlisted airman/guardian – disqualified for reasons beyond control
+    :100: Enlisted airman/guardian – disqualified for reasons within control
+    :200: Enlisted airman/guardian awaiting discharge, separation, or retirement for reasons within their control
+    :300: Enlisted airman/guardian awaiting discharge, separation, or retirement for reasons beyond their control
+    :400: Disqualified airman/guardian, return to duty program
+    :500: Enlisted airman/guardian temporarily ineligible for retraining – disqualified for reasons beyond control
+:9B:
+  :name: Senior enlisted advisor
+  :subcategories:
+    :000: Senior enlisted advisor to the chairman of the joint chiefs of staff
+    :100: Senior enlisted advisor to the chief of the National Guard Bureau
+:9C:
+  :name: Chief Master Sergeant of the Air Force
+  :subcategories:
+    :000: Chief Master Sergeant of the Air Force
+    :100: Executive assistant to the Chief Master Sergeant of the Air Force
+:9D:
+  :name: Developmental positions
+  :subcategories:
+    :100: AF developmental senior enlisted positions
+    :200: Key developmental senior enlisted positions
+:9E:
+  :name: Command Chief Master Sergeant
+  :subcategories:
+    :000: Command Chief Master Sergeant
+    :100: Command chief executive assistant
+    :200: Individual Mobilization Augmentee to Command Chief Master Sergeant
+:9F:
+  :name: First term airmen center
+  :subcategories:
+    :000: First term airmen center (FTAC) NCOIC
+:9G:
+  :name: Group senior enlisted leader
+  :subcategories:
+    :100: Group senior enlisted leader
+:9H:
+  :name: Academic and WHCA
+  :subcategories:
+    :000: Academic faculty instructor
+    :100: White House communications agency technician (WHCA)
+:9I:
+  :name: Futures airmen
+  :subcategories:
+    :000: Futures airmen
+:9J:
+  :name: Prisoner
+  :subcategories:
+    :000: Prisoner
+:9L:
+  :name: Interpreter/translator
+  :subcategories:
+    :000: Interpreter/translator
+    :100: Enlisted international affairs manager
+:9M:
+  :name: Military entrance and health
+  :subcategories:
+    :000: Military entrance processing command (MEPCOM) senior enlisted advisor
+    :200: International health specialists (IHS)
+    :400: Chief, medical enlisted force (CMEF)
+:9N:
+  :name: Legislative fellows
+  :subcategories:
+    :000: Secretary of the Air Force enlisted legislative fellows
+:9P:
+  :name: Patient
+  :subcategories:
+    :000: Patient
+:9Q:
+  :name: Reserve force
+  :subcategories:
+    :000: Reserve force generation and oversight NCO
+:9R:
+  :name: Civil Air Patrol
+  :subcategories:
+    :000: Civil Air Patrol (CAP) – USAF reserve assistance NCO
+:9S:
+  :name: Scientific applications
+  :subcategories:
+    :100: Scientific applications specialist
+:9T:
+  :name: Trainee
+  :subcategories:
+    :000: Basic enlisted airman
+    :100: Officer trainee
+    :200: Precadet assignee
+    :400: AFIT/EWI enlisted student
+    :500: Basic special warfare enlisted airman
+:9U:
+  :name: Ineligible/unallotted
+  :subcategories:
+    :000: Enlisted airman/guardian ineligible for local utilization
+    :100: Unallotted enlisted authorization
+:9V:
+  :name: Joint senior enlisted
+  :subcategories:
+    :000: Key developmental joint senior enlisted position
+    :100: Executive assistant to the senior enlisted advisor to the Chairman of the Joint Chiefs of Staff
+:9W:
+  :name: Wounded warrior
+  :subcategories:
+    :000: Combat wounded warrior
+    :100: Reserved for future use
+    :200: Combat wounded warrior with exemptions
+    :300: Non-combat wounded warrior
+    :400: Wounded warrior – limited assignment status (LAS)
+    :500: Reserved for future use
+    :600: Reserved for future use
+    :700: Reserved for future use
+    :800: Wounded warrior – ambassador
+    :900: Wounded warrior – project planner/officer
+:9Y:
+  :name: Air Force parachute team
+  :subcategories:
+    :000: Air force parachute team (AFPT) instructor
+:9Z:
+  :name: Special warfare mission support
+  :subcategories:
+    :000: Special warfare mission support (SWMS) career field manager (CFM) on headquarters Air Force staff, Air Force Special Warfare Division
+    :100: Special warfare mission support (SWMS) senior enlisted leader, Air Force Special Warfare (AFSPECWAR)
+    :200: Special warfare mission support (SWMS) superintendent, Air Force Special Warfare (AFSPECWAR)

data/lib/gov_codes/afsc.rb

@@ -1,16 +1,27 @@
 require_relative "afsc/enlisted"
 require_relative "afsc/officer"
+require_relative "afsc/ri"
 
 module GovCodes
   module AFSC
     def self.find(code)
       AFSC::Enlisted.find(code) ||
-        AFSC::Officer.find(code)
+        AFSC::Officer.find(code) ||
+        AFSC::RI.find(code)
+    end
+
+    def self.search(prefix)
+      results = []
+      results.concat(Enlisted.search(prefix))
+      results.concat(Officer.search(prefix))
+      results.concat(RI.search(prefix))
+      results
     end
 
     def self.reset_data(lookup: $LOAD_PATH)
       Enlisted.reset_data(lookup:)
       Officer.reset_data(lookup:)
+      RI.reset_data(lookup:)
     end
   end
 end

data/lib/gov_codes/data_loader.rb

@@ -11,65 +11,59 @@ module GovCodes
 
     def data(lookup: $LOAD_PATH)
       data = {}
+      lookup_array = Array(lookup)
+      return data if lookup_array.empty?
 
-      namespace_parts = name.split("::")
-        .map { |it| it.gsub(/([A-Z])([a-z])/, '_\1\2').downcase }
-        .map { |it| it.sub(/^_/, "") }
+      # Add the gem's lib directory to the lookup path
+      gem_lib_dir = File.expand_path("..", __dir__)
+      lookup_paths = [gem_lib_dir] + lookup_array
 
-      # Append .yml to the last item
+      # Convert namespace to file path parts (e.g., "GovCodes::AFSC::Enlisted" -> ["gov_codes", "afsc", "enlisted.yml"])
+      namespace_parts = name.split("::")
+        .map { |part| part.gsub(/([A-Z])([a-z])/, '_\1\2').downcase.sub(/^_/, "") }
       namespace_parts[-1] = "#{namespace_parts[-1]}.yml"
 
-      # Iterate through each path in the lookup array
-      files = lookup.map do |dir|
+      # Find all existing YAML files in lookup paths
+      lookup_paths.filter_map do |dir|
         yaml_path = File.join(dir, *namespace_parts)
         yaml_path if File.exist?(yaml_path)
-      end
-        .compact
-        .uniq
-      files.each do |path|
-        data.merge!(YAML.load_file(path, symbolize_names: true))
+      end.uniq.each do |path|
+        yaml_data = YAML.load_file(path, symbolize_names: true)
+        data.merge!(yaml_data) if yaml_data.is_a?(Hash)
+      rescue Psych::SyntaxError, TypeError
+        # Handle invalid YAML gracefully
+        next
       end
 
       data
     end
 
     def reset_data(lookup: $LOAD_PATH)
-      remove_const(:DATA)
+      remove_const(:DATA) if const_defined?(:DATA, false)
       const_set(:DATA, data(lookup:).freeze)
-      remove_const(:CODES)
+      remove_const(:CODES) if const_defined?(:CODES, false)
       const_set(:CODES, {})
     end
 
     def find_name_recursive(result)
-      # Start with the career field (e.g., "1N")
       base_code = result[:career_field].to_sym
+      base_data = self::DATA[base_code]
+      return "Unknown" unless base_data
 
-      loaded_data = self::DATA
-      # Look up in the codes hash
-      if loaded_data[base_code]
-        # If we have a subcategory, try to find a more specific name
-        if result[:subcategory] &&
-            loaded_data.dig(base_code, :subcategories) &&
-            loaded_data.dig(base_code, :subcategories, result[:subcategory])
-
-          subdivision = loaded_data.dig(base_code, :subcategories, result[:subcategory])
-          # If we have a shredout, try to find an even more specific name
-          if result[:shredout] &&
-              subdivision.dig(:subcategories) &&
-              subdivision.dig(:subcategories, result[:shredout])
-            return subdivision.dig(:subcategories, result[:shredout], :name)
+      # Try subcategory lookup if present
+      if result[:subcategory]
+        subdivision = base_data.dig(:subcategories, result[:subcategory])
+        if subdivision
+          # Try shredout lookup if present
+          if result[:shredout]
+            shredout_name = subdivision.dig(:subcategories, result[:shredout], :name)
+            return shredout_name if shredout_name
           end
-
-          # Return the subdivision name if no shredout match
-          return subdivision.dig(:name)
+          return subdivision[:name] if subdivision[:name]
         end
-
-        # Return the base name if no subdivision match
-        return loaded_data.dig(base_code, :name)
       end
 
-      # Return a default if no match found
-      "Unknown"
+      base_data[:name] || "Unknown"
     end
   end
 end

data/lib/gov_codes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GovCodes
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gov_codes
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jim Gay
@@ -22,11 +22,15 @@ files:
 - CHANGELOG.md
 - README.md
 - Rakefile
+- checksums/gov_codes-0.1.0.gem.sha512
 - lib/gov_codes.rb
 - lib/gov_codes/afsc.rb
 - lib/gov_codes/afsc/enlisted.rb
 - lib/gov_codes/afsc/enlisted.yml
 - lib/gov_codes/afsc/officer.rb
+- lib/gov_codes/afsc/officer.yml
+- lib/gov_codes/afsc/ri.rb
+- lib/gov_codes/afsc/ri.yml
 - lib/gov_codes/data_loader.rb
 - lib/gov_codes/version.rb
 - sig/gov_codes.rbs
@@ -50,7 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Handle codes used by the US government.
 test_files: []