gov_codes 0.1.1 → 0.1.2

data/lib/gov_codes/dafecd/specialty_parser.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative "patterns"
+require_relative "publication"
+require_relative "text"
+
+module GovCodes
+  module Dafecd
+    # Parses a single specialty record (as produced by RecordSplitter) into a
+    # structured header: X-form specialty, career field, CEM code (enlisted),
+    # per-specialty change date, skill/qualification ladder, and the
+    # (conservatively normalized) specialty title.
+    #
+    # Behavior is publication-specific (injected Publication); the default is the
+    # enlisted directory.
+    #
+    # Deliberately does NOT attempt to de-glue titles that pdf-reader ran
+    # together (e.g. "FORCEAVIATOR" / "SPECIALWARFARE"). Such titles are
+    # title-cased verbatim and flagged via :glued_title so the deferred LLM
+    # despacer can address them.
+    class SpecialtyParser
+      DECORATIVE = Patterns::DECORATIVE
+      UNICODE_DASHES = Patterns::UNICODE_DASHES
+
+      def initialize(record, publication: Publication.dafecd)
+        @publication = publication
+        @record = Text.split_glued_afsc(record, publication.glued_afsc)
+        @lines = @record.lines
+      end
+
+      def parse
+        codes = ladder_codes
+        {
+          specialty: specialty(codes),
+          career_field: career_field(codes),
+          cem_code: cem_code,
+          bare_code: bare_code,
+          changed_date: changed_date,
+          name: name,
+          raw_title: raw_title,
+          glued_title: glued_title?
+        }.merge(@publication.levels_key => levels)
+      end
+
+      private
+
+      def ladder
+        @publication.ladder
+      end
+
+      # @return [Array<String>] concrete ladder AFSCs in document order
+      def ladder_codes
+        @lines.filter_map { |line| line[ladder, 1] }
+      end
+
+      # The specialty key: the ladder-family X-form, or (for a bare single-code
+      # record with no ladder) the literal code.
+      def specialty(codes)
+        return @publication.specialty_key(codes) if codes.any?
+        bare = bare_code
+        bare&.to_sym
+      end
+
+      def career_field(codes)
+        return @publication.career_field(codes) if codes.any?
+        bare = bare_code
+        bare && :"#{bare[0, 2]}"
+      end
+
+      # The bare standalone code of a single-code record (officer), or nil.
+      def bare_code
+        return @bare_code if defined?(@bare_code)
+        pattern = @publication.bare_code
+        @bare_code = pattern && @record[pattern, 1]
+      end
+
+      def cem_code
+        pattern = @publication.cem
+        pattern && @record[pattern, 1]
+      end
+
+      def changed_date
+        raw = @record[@publication.change_date, 1]
+        return nil unless raw
+        Text.parse_date(raw)
+      end
+
+      # @return [Hash{Integer=>Hash}] level digit => {code:, title:}
+      def levels
+        result = {}
+        @lines.each do |line|
+          next unless line =~ ladder
+          code = $1
+          title = normalize_level($2)
+          digit = code[3].to_i
+          result[digit] = {code: code, title: title}
+        end
+        result
+      end
+
+      def normalize_level(word)
+        collapsed = word.gsub(/\s+/, " ").strip
+        (collapsed == "Senior Enlisted") ? "Senior Enlisted Leader" : collapsed
+      end
+
+      def name
+        raw = raw_title
+        return nil if raw.nil? || raw.empty?
+        titleize(raw)
+      end
+
+      def glued_title?
+        title = name
+        return false if title.nil?
+        # Heuristic proxy for pdf-reader glue: an unusually long single token
+        # (excluding preserved acronyms). Reported, not relied upon, for the
+        # deferred despacer. False positives are possible for genuinely long
+        # words; the coverage report lists them for human review.
+        title.split(/\s+/).any? do |token|
+          bare = token.delete("()/-")
+          bare.length >= 12 && bare.match?(/\A[A-Za-z]+\z/)
+        end
+      end
+
+      # The title line(s) between the last ladder/bare-code line and the change
+      # date / first numbered section, joined and sanitized (pre-titlecase).
+      # Exposed verbatim so the de-gluer can diff against the source.
+      def raw_title
+        return @raw_title if defined?(@raw_title)
+        @raw_title = compute_raw_title
+      end
+
+      def compute_raw_title
+        last_anchor = last_anchor_index
+        return nil if last_anchor.nil?
+
+        collected = []
+        @lines[(last_anchor + 1)..].each do |line|
+          stripped = sanitize(line)
+          next if stripped.empty?
+          next if stripped.match?(/\A\d+\z/)          # bare page number
+          next if stripped.match?(/\A[A-Z][a-z]+\z/)  # wrapped ladder word (e.g. "Leader")
+          break if stripped.match?(/\A\(?(?:Changed|Established|Effective)\b/) # change date
+          break if stripped.match?(/\A\d+\./)          # numbered section (1. / 1.Specialty / 3.4.1)
+          break if stripped.match?(/\b(?:Specialty Summary|Special Duty Summary|Duties and Responsibilities)\b/)
+
+          if title_line?(stripped)
+            collected << stripped
+          else
+            break
+          end
+        end
+
+        return nil if collected.empty?
+        collected.join(" ")
+      end
+
+      # The last line that anchors a record: a ladder line, or (for a bare
+      # single-code officer record) the standalone code line.
+      def last_anchor_index
+        @lines.each_index.reverse_each.find do |i|
+          @lines[i] =~ ladder || (@publication.bare_code && @lines[i] =~ @publication.bare_code)
+        end
+      end
+
+      # Remove decorative symbol glyphs, normalize unicode dashes, and collapse
+      # runs of whitespace (pdf-reader pads some titles with long space runs) so
+      # a title line reduces to its plain-text content.
+      def sanitize(line)
+        line.gsub(DECORATIVE, "").gsub(UNICODE_DASHES, "-").gsub(/\s+/, " ").strip
+      end
+
+      # A title line is short, starts with a capital / paren / digit, and is not
+      # a prose sentence. Accepts ALL-CAPS and Title-Case forms; the boundary
+      # breaks in compute_raw_title stop collection before the summary prose.
+      def title_line?(stripped)
+        return false if stripped.length > 70
+        return false unless stripped.match?(/\A[A-Z0-9(]/)
+        return false if stripped.split(/\s+/).size > 10
+        return false if stripped.match?(/[a-z]\.\s+[A-Z]/) # mid-line sentence break = prose
+        stripped.match?(/[A-Za-z]/)
+      end
+
+      def titleize(raw)
+        raw.split(/\s+/).map { |word| titleize_word(word) }.join(" ")
+      end
+
+      def titleize_word(word)
+        # Preserve parenthesized acronyms, e.g. "(RPA)", "(ISR)", "(C2)".
+        return word if word.match?(/\A\([A-Z0-9&\/.-]{2,}\)\z/)
+        # Preserve all-caps tokens containing a digit, e.g. "C2", "F16".
+        return word if word.match?(/\A[A-Z]*\d[A-Z0-9]*\z/) && word.match?(/[A-Z0-9]/)
+
+        word.split(/([\/-])/).map { |seg|
+          seg.match?(/[A-Za-z]/) ? seg.capitalize : seg
+        }.join
+      end
+    end
+  end
+end

data/lib/gov_codes/dafecd/text.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GovCodes
+  module Dafecd
+    # Shared text utilities for the DAFECD extractor: normalization of
+    # pdf-reader glue artifacts and date parsing. Used by RecordSplitter,
+    # SpecialtyParser, and the extractor CLI so the behavior stays consistent.
+    module Text
+      MONTHS = %w[jan feb mar apr may jun jul aug sep oct nov dec]
+        .each_with_index.to_h { |m, i| [m, i + 1] }.freeze
+
+      # Default (enlisted) glue boundary: a letter immediately followed by an
+      # "AFSC <5-char enlisted code>".
+      DEFAULT_GLUED_AFSC = /(?<=[A-Za-z])(?=AFSC \d[A-Z]\d\d\d)/
+
+      module_function
+
+      # pdf-reader frequently glues the word "AFSC" to a preceding word when a
+      # ladder line wraps, e.g. "LeaderAFSC 1A178*, Craftsman". Insert a newline
+      # before an "AFSC <code>" that is glued to a letter so the ladder line is
+      # detectable at line start. This is safe for prose mentions such as
+      # "possession ofAFSC 1A132" because ladder detection additionally requires
+      # a skill-level word at end of line, which prose lines do not satisfy.
+      #
+      # The glue boundary is publication-specific (the enlisted and officer AFSC
+      # code shapes differ); pass the publication's pattern to override the
+      # enlisted default.
+      def split_glued_afsc(text, pattern = DEFAULT_GLUED_AFSC)
+        text.gsub(pattern, "\n")
+      end
+
+      # Normalize a directory date such as "31 Oct 25", "31 Oct 2024", or the
+      # officer directory's glued "30Apr 25" to ISO 8601 ("2025-10-31" /
+      # "2024-10-31"). The day/month gap is optional (\s*) to absorb pdf-reader's
+      # glued day/month; the enlisted (always-spaced) dates are unaffected.
+      # Returns nil when unparseable.
+      def parse_date(raw)
+        return nil unless raw =~ /(\d{1,2})\s*(\w{3,9})\s+(\d{2,4})/
+        day = $1.to_i
+        month = MONTHS[$2[0, 3].downcase]
+        year = $3.to_i
+        year += 2000 if year < 100
+        return nil unless month
+        format("%04d-%02d-%02d", year, month, day)
+      end
+    end
+  end
+end

data/lib/gov_codes/dafecd/title_degluer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module GovCodes
+  module Dafecd
+    # Applies verified de-glued specialty titles.
+    #
+    # pdf-reader drops spaces inside DAFECD titles ("MOBILITY FORCEAVIATOR").
+    # The deterministic extractor title-cases those verbatim ("Mobility
+    # Forceaviator") and cannot safely re-insert the missing spaces. The clean
+    # titles are produced out of band and shipped in title_overrides.yml.
+    #
+    # The de-gluing invariant — enforced at build time by IndexBuilder — is that
+    # an override may only change SPACING and CASE relative to the raw source
+    # title; no letter, digit, or punctuation may change. Any drift (e.g. a
+    # future release renamed the specialty) fails the build loudly rather than
+    # silently applying a stale title.
+    class TitleDegluer
+      DEFAULT_PATH = File.expand_path("title_overrides.yml", __dir__)
+
+      # @return [TitleDegluer] loaded from the shipped overrides file
+      def self.load(path = DEFAULT_PATH)
+        overrides = YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+        new(overrides)
+      end
+
+      # @return [TitleDegluer] loaded from +publication+'s overrides file, or an
+      #   empty de-gluer when that file does not yet exist (officer titles are
+      #   supplied out of band in a later phase).
+      def self.for(publication)
+        path = publication.title_overrides_path
+        File.exist?(path) ? load(path) : empty
+      end
+
+      # An empty de-gluer applies no overrides (keeps the auto-titlecased names).
+      def self.empty
+        new({})
+      end
+
+      # Whitespace-and-case-insensitive normalization used for the invariant.
+      def self.norm(str)
+        str.to_s.gsub(/\s+/, "").downcase
+      end
+
+      # Does +override+ differ from +raw_title+ only in spacing/case?
+      def self.matches_source?(override, raw_title)
+        return false if raw_title.nil?
+        norm(override) == norm(raw_title)
+      end
+
+      # @param overrides [Hash{Symbol=>String}] specialty => clean title
+      def initialize(overrides = {})
+        @overrides = overrides
+      end
+
+      # @return [String, nil] the clean title for +specialty+, or nil
+      def override_for(specialty)
+        @overrides[specialty]
+      end
+
+      def any?
+        !@overrides.empty?
+      end
+    end
+  end
+end

data/lib/gov_codes/dafecd/title_overrides/dafocd.yml

@@ -0,0 +1,141 @@
+# De-glued specialty titles for DAFOCD, effective 2025-10-31.
+# Each value is the source PDF title with ONLY spacing/case adjusted --
+# no letters, digits, or punctuation changed. Enforced at build time by
+# the IndexBuilder verification gate (whitespace/case-insensitive
+# equality against the raw source title); drift fails the build.
+:10C0: Operations Commander
+:11BX: Bomber Pilot
+:11EX: Experimental Test Pilot
+:11FX: Fighter Pilot
+:11GX: Generalist Pilot
+:11HX: Rescue Pilot
+:11KX: Trainer Pilot
+:11MX: Mobility Pilot
+:11RX: Reconnaissance/Surveillance/Electronic Warfare Pilot
+:11SX: Special Operations Pilot
+:11TX: Student Pilot
+:11UX: Remotely Piloted Aircraft (RPA) Pilot
+:12BX: Bomber Combat Systems Officer
+:12EX: Experimental Test Combat Systems Officer
+:12FX: Fighter Combat Systems Officer
+:12GX: Generalist Combat Systems Officer
+:12HX: Rescue Combat Systems Officer
+:12KX: Trainer Combat Systems Officer
+:12MX: Mobility Combat Systems Officer
+:12RX: Reconnaissance/Surveillance/Electronic Warfare Combat Systems Officer
+:12SX: Special Operations Combat Systems Officer
+:12UX: Remotely Piloted Aircraft (RPA) Combat Systems Officer
+:13AX: Astronaut
+:13BX: Air Battle Manager
+:13HX: Aerospace Physiologist
+:13MX: Airfield Operations
+:13NX: Nuclear and Missile Operations
+:13OX: Multi-Domain Warfare Officer
+:13SX: Space Operations
+:13ZX: Rated Multi-Domain Warfare Officer
+:14FX: Information Operations
+:14NX: Intelligence
+:15AX: Operations Analysis Officer
+:15WX: Weather and Environmental Sciences
+:16FX: Foreign Area Officer (FAO)
+:16GX: Air Force Operations Staff Officer
+:16KX: Software Development Officer (SDO)
+:16PX: Political-Military Affairs Strategist (PAS)
+:16RX: Planning and Programming
+:16ZX: Rated Foreign Area Officer (FAO)
+:17DX: Warfighter Communications
+:17SX: Cyberspace Effects Operations
+:17WX: Warfighter Communications & IT Systems
+:17YX: Cyber Effects & Warfare Operations
+:18AX: Attack Remotely Piloted Aircraft Pilot
+:18EX: Experimental Test Remotely Piloted Aircraft Pilot
+:18GX: Generalist Remotely Piloted Aircraft Pilot
+:18RX: Reconnaissance Remotely Piloted Aircraft Pilot
+:18SX: Special Operations Remotely Piloted Aircraft Pilot
+:19ZX: Special Warfare
+:20C0: Logistics Commander
+:21AX: Aircraft Maintenance
+:21MX: Munitions and Missile Maintenance
+:21RX: Logistics Readiness
+:30C0: Support Commander
+:31PX: Security Forces
+:32EX: Civil Engineer
+:35BX: Band
+:35PX: Public Affairs
+:38FX: Force Support
+:40C0: Medical Commander
+:41AX: Healthcare Administrator
+:42BX: Physical Therapist
+:42EX: Optometrist
+:42FX: Podiatric Surgeon
+:42GX: Physician Assistant
+:42NX: Audiologist
+:42PX: Clinical Psychologist
+:42SX: Clinical Social Worker
+:42TX: Occupational Therapist
+:43BX: Biomedical Scientist
+:43DX: Dietitian
+:43EX: Bioenvironmental Engineer
+:43HX: Public Health Officer
+:43PX: Pharmacist
+:43TX: Biomedical Laboratory
+:44AX: Chief of Medical Staff
+:44BX: Preventive Medicine Physician
+:44DX: Pathologist
+:44EX: Emergency Medicine Physician
+:44FX: Family Physician
+:44GX: General Practice Physician
+:44HX: Nuclear Medicine Physician
+:44JX: Medical Geneticist and Genomicist
+:44KX: Pediatrician
+:44MX: Internal Medicine Physician
+:44NX: Neurologist
+:44OX: Physician
+:44PX: Psychiatrist
+:44RX: Radiologist
+:44SX: Dermatologist
+:44TX: Radiation Oncologist
+:44UX: Occupational Medicine Physician
+:44YX: Critical Care Medicine Physician
+:44ZX: Allergist and Immunologist
+:45AX: Anesthesiologist
+:45BX: Orthopaedic Surgeon
+:45EX: Ophthalmologist
+:45GX: Gynecologic Surgeon and Obstetrician
+:45NX: Otolaryngologist - Head and Neck Surgeon
+:45PX: Physical Medicine Physician
+:45SX: Surgeon
+:45UX: Urologist
+:46AX: Nursing Administrator
+:46FX: Flight Nurse
+:46NX: Clinical Nurse
+:46PX: Mental Health Nurse
+:46SX: Operating Room Nurse
+:46YX: Advanced Practice Registered Nurse (APRN)
+:47BX: Orthodontist
+:47DX: Oral and Maxillofacial Pathologist
+:47EX: Endodontist
+:47GX: Dentist
+:47HX: Periodontist
+:47KX: Pediatric Dentist
+:47PX: Prosthodontist
+:47SX: Oral and Maxillofacial Surgeon
+:48AX: Aerospace Medicine Physician Specialist
+:48GX: General Medical Officer (GMO), Flight Surgeon
+:48OX: Aeromedical Physician
+:48RX: Residency Trained Flight Surgeon
+:48VX: Pilot-Physician
+:51JX: Judge Advocate
+:52RX: Chaplain
+:60C0: Senior Materiel Leader-Upper Echelon
+:61CX: Chemist/Nuclear Chemist
+:61DX: Physicist/Nuclear Engineer
+:62EX: Developmental Engineer
+:62S0: Materiel Leader
+:63AX: Acquisition Manager
+:63G0: Senior Materiel Leader-Lower Echelon
+:63S0: Materiel Leader
+:64PX: Contracting
+:65FX: Financial Management
+:65WX: Cost Analysis
+:71SX: Special Investigations

data/lib/gov_codes/dafecd/title_overrides.yml

@@ -0,0 +1,142 @@
+# De-glued specialty titles for DAFECD, effective 2025-10-31.
+# Each value is the source PDF title with ONLY spacing/case adjusted --
+# no letters, digits, or punctuation changed. Enforced at build time:
+# the IndexBuilder verifies each override against the raw source title
+# (whitespace-and-case-insensitive equality) and fails the build on drift.
+# Produced as the governed de-gluing step for pdf-reader space loss.
+:1A1X2: Mobility Force Aviator
+:1A1X3: Special Mission Aviator
+:1A1X4: Multi-Domain Operations Aviator
+:1A1X8: Executive Mission Aviator
+:1A8X0: SEL Airborne Intelligence, Surveillance and Reconnaissance (ISR)
+:1A8X1: Airborne Cryptologic Language Analyst (ACLA)
+:1A8X2: Airborne Intelligence, Surveillance, and Reconnaissance (ISR) Operator
+:1B4X1: Cyber Warfare Operations
+:1C0X2: Aviation Resource Management
+:1C1X1: Air Traffic Control
+:1C3X1: All-Domain Command and Control Operations
+:1C5X1: Battle Management Operations
+:1C6X1: Space Systems Operations
+:1C7X1: Airfield Management
+:1C8X3: Radar, Airfield & Weather Systems (RAWS)
+:1D7X1: Warfighter Communications
+:1D7X2: Radio Frequency Transmissions and Electromagnetic Activities (EMA)
+:1D7X3: Cable and Antenna
+:1D7X4: Data Engineering
+:1D7X5: Cybersecurity
+:1H0X1: Aerospace Physiology
+:1N0X1: All Source Intelligence Analyst
+:1N0X2: Intelligence Superintendent
+:1N1X1: Geospatial Intelligence (GEOINT)
+:1N2X1: Signals Intelligence
+:1N2X2: Cryptologic Intelligence Superintendent
+:1N3X1: Cryptologic Language Analyst
+:1N4X1: Cyber Intelligence
+:1N4X2: Cryptologic Analyst & Reporter
+:1N7X1: Human Intelligence Specialist
+:1N8X1: Targeting Analyst
+:1P0X1: Aircrew Flight Equipment
+:1S0X1: Safety
+:1T0X1: Survival, Evasion, Resistance, Escape (SERE) Specialist
+:1U1X1: Remotely Piloted Aircraft (RPA) Pilot
+:1W0X1: Weather
+:1Z1X1: Pararescue
+:1Z2X1: Combat Control
+:1Z3X1: Tactical Air Control Party (TACP)
+:1Z4X1: Special Reconnaissance
+:2A0X0: Avionics
+:2A0X1: Avionics Test Station, Components, and Electronic Warfare Systems
+:2A2X1: MHU-139 Electrical, Environmental and Avionics Technician
+:2A3X0: Fighter Aircraft Maintenance
+:2A3X3: Tactical Aircraft Maintenance
+:2A3X4: Fighter Aircraft Integrated Avionics
+:2A3X5: Advanced Fighter Aircraft Integrated Avionics
+:2A3X7: Tactical Aircraft Maintenance (5th Generation)
+:2A5X0: Airlift/Special Mission Aircraft Maintenance Superintendent
+:2A5X1: Airlift/Special Mission Aircraft Maintenance
+:2A5X2: Helicopter/Tiltrotor Aircraft Maintenance
+:2A5X4: Refuel/Bomber Aircraft Maintenance
+:2A6X0: Aircraft Accessories
+:2A6X1: Aerospace Propulsion
+:2A6X2: Aerospace Ground Equipment
+:2A6X3: Aircrew Egress Systems
+:2A6X4: Aircraft Fuel Systems
+:2A6X5: Aircraft Hydraulic Systems
+:2A6X6: Aircraft Electrical and Environmental Systems
+:2A7X0: Aircraft Fabrication
+:2A7X1: Aircraft Metals Technology
+:2A7X2: Nondestructive Inspection
+:2A7X3: Aircraft Structural Maintenance
+:2A9X4: Heavy Aircraft Integrated Avionics
+:2F0X1: Fuels
+:2G0X1: Logistics Plans
+:2M0X0: Missile and Space Systems Maintenance
+:2M0X1: Missile and Space Systems Electronic Maintenance
+:2M0X2: Missile and Space Systems Maintenance
+:2M0X3: Missile and Space Facilities
+:2P0X1: Precision Measurement Equipment Laboratory
+:2R2X1: Maintenance Management
+:2S0X1: Materiel Management
+:2T0X1: Traffic Management Operations
+:2T1X1: Ground Transportation
+:2T2X1: Air Transportation
+:2T3X0: Vehicle Management
+:2T3X1: Mission Generation Vehicular Equipment Maintenance
+:2T3X7: Fleet Management and Analysis
+:2W0X1: Munitions Systems
+:2W1X1: Aircraft Armament Systems
+:2W2X1: Nuclear Weapons
+:3E0X0: Facility Systems
+:3E0X1: Electrical Systems
+:3E0X2: Electrical Power Production
+:3E1X1: Heating, Ventilation, Air Conditioning, and Refrigeration
+:3E2X0: Heavy Repair
+:3E2X1: Pavements and Construction Equipment
+:3E3X1: Structural
+:3E4X0: Infrastructure Systems
+:3E4X1: Water and Fuel Systems Maintenance
+:3E4X3: Pest Management
+:3E5X1: Engineering
+:3E6X1: Operations Management
+:3E7X1: Fire Protection
+:3E8X1: Explosive Ordnance Disposal
+:3E9X1: Emergency Management
+:3F0X1: Human Resources and Administration
+:3F1X1: Services
+:3F2X1: Education and Training
+:3F3X1: Manpower
+:3F4X1: Equal Opportunity
+:3G0X1: Talent Acquisition
+:3H0X1: Historian
+:3N0X0: Public Affairs
+:3N0X6: Public Affairs
+:3N1X1: Regional Band
+:3N2X1: Premier Band - The USAF Band
+:3N3X1: Premier Band - The USAF Academy Band
+:3P0X1: Security Forces
+:4A0X1: Health Services Management
+:4A1X1: Medical Materiel
+:4A2X1: Biomedical Equipment
+:4B0X1: Bioenvironmental Engineering (BE)
+:4C0X1: Mental Health Service
+:4D0X1: Diet Therapy
+:4E0X1: Public Health
+:4H0X1: Respiratory Care Practitioner
+:4J0X2: Physical Medicine
+:4N0X1: Aerospace Medical Service
+:4N1X1: Surgical Technologist
+:4P0X1: Pharmacy
+:4R0X1: Diagnostic Imaging
+:4T0X0: Medical Laboratory
+:4T0X1: Medical Laboratory
+:4T0X2: Histopathology
+:4V0X1: Ophthalmic
+:4Y0X0: Dental
+:4Y0X1: Dental Assistant
+:4Y0X2: Dental Laboratory
+:5J0X1: Paralegal
+:5R0X1: Religious Affairs
+:6C0X1: Contracting
+:6F0X1: Financial Management and Comptroller
+:7S0X1: Special Investigations
+:8G0X1: Premier Honor Guard

data/lib/gov_codes/data_loader.rb

@@ -45,6 +45,25 @@ module GovCodes
       const_set(:CODES, {})
     end
 
+    # Load and merge a flat overlay YAML map (e.g. a consumer acronyms overlay)
+    # named +basename+ under gov_codes/afsc across the load path. Files loaded
+    # later win, so a consumer file merges over any shipped one. Returns {} when
+    # none exist; malformed files are skipped (graceful degradation).
+    def flat_overlay(basename, lookup: $LOAD_PATH)
+      merged = {}
+      gem_lib_dir = File.expand_path("..", __dir__)
+      ([gem_lib_dir] + Array(lookup)).uniq.each do |dir|
+        path = File.join(dir, "gov_codes", "afsc", basename)
+        next unless File.exist?(path)
+
+        overlay = YAML.load_file(path, symbolize_names: true)
+        merged.merge!(overlay) if overlay.is_a?(Hash)
+      rescue Psych::SyntaxError, TypeError
+        next
+      end
+      merged
+    end
+
     def find_name_recursive(result)
       base_code = result[:career_field].to_sym
       base_data = self::DATA[base_code]

data/lib/gov_codes/version.rb

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