gov_codes 0.1.1 → 0.1.2

data/lib/gov_codes/afsc/officer.rb

@@ -1,9 +1,12 @@
 require "strscan"
-require "yaml"
-require_relative "../data_loader"
+require_relative "releases"
 
 module GovCodes
   module AFSC
+    # Officer AFSCs resolved against the versioned DAFOCD release index. Mirrors
+    # Enlisted: +find(code, as_of:)+ resolves the X-form specialty (e.g. :11BX)
+    # or a literal bare code (e.g. :10C0) in the release in effect on +as_of+,
+    # defaulting to today.
     module Officer
       class Parser
         def initialize(code)
@@ -53,91 +56,144 @@ module GovCodes
         end
       end
 
-      extend GovCodes::DataLoader
-
-      DATA = data
+      CODES = {}
+      private_constant :CODES
 
       Code = Data.define(
         :prefix,
         :career_group,
         :functional_area,
         :qualification_level,
+        :qualification_level_number,
+        :qualification_level_name,
         :shredout,
+        :shredout_name,
+        :specialty,
+        :specialty_name,
         :specific_afsc,
-        :name
+        :name,
+        :acronym,
+        :effective_date
       )
 
-      def self.find_name_recursive(result)
-        name = nil
-        data = DATA
-
-        # For officer codes, build the lookup key from career group + functional area + qual level
-        # like "11BX" where "11" is career group, "B" is functional area, "X" is qual level
-        career_group = result[:career_group].to_s
-        functional_area = result[:functional_area].to_s
-        qual_level = result[:qualification_level].to_s
-        combined_key = :"#{career_group}#{functional_area}#{qual_level}"
-
-        # Look for the full code (e.g., "11BX", "11MX")
-        if data[combined_key]
-          name = data[combined_key][:name]
-          data = data[combined_key][:subcategories]
-
-          # Then look for shredout
-          if data && result[:shredout]
-            shred = result[:shredout]
-            # Try Symbol first (most shredouts are letters), then Integer, then String
-            lookup_value = data[shred] || data[shred.to_s.to_i] || data[shred.to_s]
-            if lookup_value
-              name = lookup_value.is_a?(Hash) ? (lookup_value[:name] || name) : (lookup_value || name)
-            end
+      # Resolve an officer AFSC against the DAFOCD release in effect on +as_of+
+      # (default: today). Returns nil when the code does not parse, when neither
+      # the X-form specialty nor a literal bare code resolves in the release, or
+      # when +as_of+ precedes the earliest shipped release (or no release has
+      # taken effect yet).
+      def self.find(code, as_of: nil)
+        code = code.to_s
+        # Key the memo on the RESOLVED release date so equivalent as_of values
+        # (nil, the Date, its string form, any date in the same release window)
+        # share one slot instead of growing unbounded for time-series callers.
+        effective_date = Releases.effective_date_for(as_of: as_of, publication: Releases::OFFICER_PUBLICATION)
+        CODES[[code, effective_date]] ||= begin
+          result = Parser.new(code).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[:functional_area].nil? ||
+            result[:qualification_level].nil? ||
+            result[:specific_afsc].nil?
+
+          index = Releases.officer_index(as_of: as_of)
+
+          # Prefer the X-form specialty key (11B3 -> :11BX). Fall back to the
+          # literal 4-char code for bare specialties keyed that way (:10C0, :62S0,
+          # :63G0, :63S0). By design these bare-code specialties resolve ONLY via
+          # their literal code -- there is no X-form ladder for them, so
+          # find("10CX")/find("62SX")/find("63GX")/find("63SX") return nil while
+          # find("10C0")/find("62S0")/find("63G0")/find("63S0") resolve.
+          specialty = :"#{result[:career_group]}#{result[:functional_area]}X"
+          if !index.key?(specialty) && index.key?(result[:specific_afsc])
+            specialty = result[:specific_afsc]
           end
-        end
-
-        name || "Unknown"
-      end
 
-      def self.find(code)
-        code = code.to_s
-        parser = Parser.new(code)
-        result = parser.parse
+          entry = index[specialty]
+          return nil unless entry
+
+          result[:specialty] = specialty
+          result[:specialty_name] = entry[:name]
+
+          # Qualification-level title: numeric level (1-4) maps to the directory's
+          # per-specialty title; a letter (X/Y/Z) or an absent level leaves it nil.
+          result[:qualification_level_number] = nil
+          result[:qualification_level_name] = nil
+          qual = result[:qualification_level].to_s
+          if qual.match?(/\d/)
+            number = Integer(qual)
+            result[:qualification_level_number] = number
+            result[:qualification_level_name] = entry.dig(:qual_levels, number, :title)
+          end
 
-        return nil if result.reject { |_, v| v.nil? }.empty?
+          # Shredout meaning, only when the directory documents this shredout.
+          shredout = result[:shredout]
+          shredout_name = shredout && entry.dig(:shredouts, shredout)
+          result[:shredout_name] = shredout_name
 
-        # Find the name by recursively searching the codes hash
-        name = find_name_recursive(result)
+          name = shredout_name || entry[:name]
+          return nil if name.nil?
+          result[:name] = name
 
-        # Add the name to the result
-        result[:name] = name
+          # Acronym: a documented shredout acronym wins for a shredded code;
+          # otherwise the specialty acronym (which a consumer overlay may set).
+          shredout_acronym = shredout && entry.dig(:shredout_acronyms, shredout)
+          result[:acronym] = shredout_acronym || entry[:acronym]
+          result[:effective_date] = effective_date
 
-        Code.new(**result)
+          Code.new(**result)
+        end
       end
 
-      def self.search(prefix)
-        results = []
-        prefix = prefix.to_s.upcase
-        collect_codes_recursive(DATA, "", prefix, results)
-        results.map { |code| find(code) }.compact
+      # Resolve the officer specialty/shredout whose acronym matches +acronym+
+      # (case-insensitive) in the release in effect on +as_of+. Searches both
+      # specialty acronyms and shredout acronyms; a shredout match returns the
+      # concrete shredded code (so "TACPO" resolves find("19ZXB")). First match
+      # wins: entries are scanned in index order and, within an entry, the
+      # specialty acronym is tried before its shredout acronyms. Returns nil when
+      # no acronym in the resolved release matches (no leakage across dates).
+      def self.find_by_acronym(acronym, as_of: nil)
+        acronym = acronym.to_s.upcase
+        return nil if acronym.empty?
+
+        index = Releases.officer_index(as_of: as_of)
+        index.each do |specialty, entry|
+          return find(specialty.to_s, as_of: as_of) if entry[:acronym].to_s.upcase == acronym
+
+          (entry[:shredout_acronyms] || {}).each do |shredout, acr|
+            return find("#{specialty}#{shredout}", as_of: as_of) if acr.to_s.upcase == acronym
+          end
+        end
+        nil
       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)
+      # Walk the resolved index emitting each specialty code and its
+      # specialty+shredout combinations, returning the Codes matching +prefix+.
+      def self.search(prefix, as_of: nil)
+        prefix = prefix.to_s.upcase
+        index = Releases.officer_index(as_of: as_of)
+
+        codes = []
+        index.each do |specialty, entry|
+          specialty_code = specialty.to_s
+          codes << specialty_code
+          (entry[:shredouts] || {}).each_key do |shredout|
+            codes << "#{specialty_code}#{shredout}"
           end
         end
+
+        codes.select { |code| code.start_with?(prefix) }
+          .map { |code| find(code, as_of: as_of) }
+          .compact
+      end
+
+      # Clears the memoized lookups and resets the versioned release loader. The
+      # +lookup+ keyword is accepted for interface parity with Enlisted/RI; the
+      # versioned index is resolved from the load path at lookup time.
+      def self.reset_data(lookup: $LOAD_PATH)
+        Releases.reset!
+        CODES.clear
       end
     end
   end