gov_codes 0.1.0 → 0.1.2

data/lib/gov_codes/dafecd/ri_sdi/title.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../patterns"
+
+module GovCodes
+  module Dafecd
+    module RiSdi
+      # Conservative title normalization for RI/SDI records.
+      #
+      # These helpers mirror the AFSC SpecialtyParser's title handling exactly
+      # (sanitize -> title-case verbatim, flag probable pdf glue) but live in
+      # their own module so the RI/SDI extraction shares NONE of the AFSC ladder
+      # pipeline's mutable state — the already-shipped enlisted/officer artifacts
+      # cannot be perturbed by anything done here.
+      #
+      # As in the AFSC pipeline, no de-gluing is attempted: a run-together title
+      # like "ENLISTEDAIDE" becomes "Enlistedaide" and is flagged via #glued? for
+      # the deferred, governed de-glue pass. Clean titles are authored out of band.
+      module Title
+        DECORATIVE = Patterns::DECORATIVE
+        UNICODE_DASHES = Patterns::UNICODE_DASHES
+
+        module_function
+
+        # Remove decorative symbol glyphs, normalize unicode dashes, and collapse
+        # whitespace 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.
+        def title_line?(stripped)
+          return false if stripped.length > 90
+          return false unless stripped.match?(/\A[A-Z0-9(]/)
+          return false if stripped.split(/\s+/).size > 12
+          return false if stripped.match?(/[a-z]\.\s+[A-Z]/) # mid-line sentence break = prose
+          stripped.match?(/[A-Za-z]/)
+        end
+
+        # Conservative title-case: capitalize each alphabetic word, preserving
+        # parenthesized acronyms and all-caps-with-digit tokens.
+        def titleize(raw)
+          raw.split(/\s+/).map { |word| titleize_word(word) }.join(" ")
+        end
+
+        def titleize_word(word)
+          return word if word.match?(/\A\([A-Z0-9&\/.-]{2,}\)\z/)
+          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
+
+        # A real title starts with a capital letter, a digit, or an opening paren
+        # — never the lowercase word that begins a wrapped prose sentence (the
+        # "SDI 8P000, completion of ..." false positive).
+        def real?(title)
+          t = title.to_s.strip
+          !t.empty? && t.match?(/\A[A-Z0-9(]/)
+        end
+
+        # Heuristic proxy for pdf-reader glue: an unusually long single token
+        # (excluding preserved acronyms). Reported, not relied upon.
+        def glued?(name)
+          return false if name.nil?
+          name.split(/\s+/).any? do |token|
+            bare = token.delete("()/-")
+            bare.length >= 12 && bare.match?(/\A[A-Za-z]+\z/)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# De-glued RI/SDI 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/case-insensitive equality) and fails the build on drift.
+:5I000: Intelligence, Surveillance & Reconnaissance Superintendent
+:5Z700: Space Operations Senior Enlisted Leader (USSF Only)
+:8A200: Enlisted Aide
+:8A300: Protocol
+:8A400: Talent Management Consultant
+:8B000: Miltary Training Instructor
+:8B100: Military Training Leader
+:8B200: Academy Military Training NCO
+:8B300: Officer Accessions Intructor
+:8B400: Military Training Instructor (Space Force)
+:8B500: Guardian Training Leader
+:8C000: Military and Family Readiness Non-Commissioned Officer (RNCO)
+:8D100: Language & Culture Advisor
+:8F000: First Sergeant
+:8F100: Guardian First Sergeant
+:8G000: Premier Honor Guard
+:8G100: Base Honor Guard Program Manager
+:8G200: Premier Honor Guard (Space Force)
+:8H000: Airmen Dorm Leader
+:8I000: Superintendent, Inspector General
+:8I100: Inspections Coordinator
+:8I200: Complaints & Resolution Coordinator
+:8K000: Software Development Specialist
+:8L100: Air Advisor - Basic
+:8L200: Air Advisor Basic, Team Sergeant
+:8L300: Air Advisor Basic, Team Leader
+:8L400: Air Advisor Advanced
+:8L500: Air Advisor Advanced, Team Sergeant
+:8L600: Air Advisor Advanced, Team Leader
+:8L700: Combat Aviation Advisor
+:8L800: Combat Aviation Advisor Team Sergeant
+:8L900: Combat Aviation Advisor Team Leader
+:8P000: Courier
+:8P100: Defense Attaché
+:8R000: Enlisted Accessions Recruiter
+:8R100: Guardian Talent Scout
+:8R200: Second-Tier Recruiter
+:8R300: Third-Tier Recruiter
+:8S000: Missile Facility Manager
+:8S200: Combat Crew Communications
+:8T000: Professional Military Education Instructor
+:8T100: Enlisted Professional Military Education Instructional System Designer
+:8T200: Development Advisor
+:8T300: Professional Military Education Instructor (Space Force)
+:8U000: Unit Deployment Manager
+:8U100: Weapons of Mass Destruction Civil Support Team (WMD-CST)
+:8W000: Weapons Safety Manager - Wing Level
+:8W100: Weapons Safety Manager
+:8W200: Second-Tier Weapons Safety Manager
+:8W300: Third-Tier Weapons Safety Manager
+:8X100: Operational STEM Specialist
+:8Y000: Pathfinder
+:9A000: Enlisted Airman/Guardian - Disqualified for Reasons Beyond Control
+:9A100: Enlisted Airman/Guardian - Disqualified for Reasons Within Control
+:9A200: Enlisted Airman/Guardian Awaiting Discharge, Separation, or Retirement for
+  Reasons Within Their Control
+:9A300: Enlisted Airman/Guardian Awaiting Discharge, Separation, or Retirement for
+  Reasons Beyond Their Control
+:9A400: Disqualified Airman/Guardian, Return to Duty Program
+:9A500: Enlisted Airman/Guardian Temporarily Ineligible for Retraining - Disqualified
+  for Reasons Beyond Control
+:9B000: Senior Enlisted Advisor to the Chairman of the Joint Chiefs of Staff
+:9B100: Senior Enlisted Advisor to the Chief of the National Guard Bureau (CNGB)
+:9C000: Chief Master Sergeant of the Air Force
+:9C100: Executive Assistant to the Chief Master Sergeant of the Air Force
+:9D100: AF Developmental Senior Enlisted Positions
+:9D200: Key Developmental Senior Enlisted Positions
+:9D300: Wing (Wing level) or Headquarter (HQ level) Senior Enlisted Leader
+:9E000: Command Chief Master Sergeant
+:9E100: Command Chief Executive Assistant
+:9E200: Individual Mobilization Augmentee to Command Chief Master Sergeant
+:9F000: First Term Enlisted Course (FTEC) NCOIC
+:9G100: Group Senior Enlisted Leader
+:9H000: Academic Faculty Instructor
+:9H100: White House Communications Agency Technician (WHCA)
+:9H200: Academic Faculty Instructor (Space Force)
+:9I000: Futures Airmen
+:9J000: Prisoner
+:9L000: Interpreter/Translator
+:9L100: International Affairs Specialist
+:9M000: Military Entrance Processing Command (MEPCOM) Senior Enlisted Advisor
+:9M200: International Health Specialists (IHS)
+:9M400: Chief, Medical Enlisted Force (CMEF), Senior Enlisted Leader and/or Senior
+  Enlisted Advisor (SEA)
+:9N000: Secretary of the Air Force Enlisted Legislative Fellows
+:9N100: Secretary of the Air Force Enlisted Legislative Fellows (Space Force)
+:9N200: DAF World Class Athlete Program (WCAP)
+:9P000: Patient
+:9Q000: Reserve Force Generation and Oversight NCO
+:9R000: Civil Air Patrol (CAP)-USAF Reserve Assistance NCO
+:9S000: Chief Master Sergeant of the Space Force
+:9S100: Scientific Applications Specialist
+:9T000: Basic Enlisted Airman
+:9T100: Officer Trainee
+:9T200: Precadet Assignee
+:9T400: AFIT/EWI Enlisted Students
+:9T500: Basic Special Warfare Enlisted Airman
+:9U000: Enlisted Airman/Guardian Ineligible for Local Utilization
+:9U100: Unallotted Enlisted Authorization
+:9V000: Key Developmental Joint Senior Enlisted Position
+:9V100: Executive Assistant to the Senior Enlisted Advisor to the Chairman of the
+  Joint Chiefs of Staff
+:9W000: Combat Wounded Warrior
+:9W100: Reserved for Future Use
+:9W200: Combat Wounded Warrior with Exemptions
+:9W300: Non-Combat Wounded Warrior
+:9W400: Wounded Warrior - Limited Assignment Status (LAS)
+:9W500: Reserved for Future Use
+:9W600: Reserved for Future Use
+:9W700: Reserved for Future Use
+:9W800: Wounded Warrior - Ambassador
+:9W900: Wounded Warrior - Project Planner/Officer
+:9Y000: Air Force Parachute Team (AFPT) Instructor
+:9Z000: Special Warfare Mission Support (SWMS) Career Field Manager (CFM) on Headquarters
+  Air Force Staff, Air Force Special Warfare Division
+:9Z100: Special Warfare Mission Support (SWMS) Senior Enlisted Leader, Air Force Special
+  Warfare (AFSPECWAR)
+:9Z200: Special Warfare Mission Support (SWMS) Superintendent, Air Force Special Warfare
+  (AFSPECWAR)

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

@@ -0,0 +1,78 @@
+# De-glued RI/SDI 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: the
+# IndexBuilder verifies each override against the raw source title
+# (whitespace/case-insensitive equality) and fails the build on drift.
+:80C0: Commander, Cadet Squadron, USAF Academy
+:81C0: Instructor, Officer Training School
+:81D0: Air Force Reserve Officer Training Corps Detachment Commander and Professor
+  of Aerospace Studies
+:81L0: Education and Training Leader
+:81T0: Instructor
+:82A0: Academic Program Manager
+:83R0: Recruiting Service
+:84H0: Historian
+:85G0: Honor Guard
+:86M0: Operations Management
+:86P0: Command and Control
+:87G0: Wing Inspector General
+:87I0: Director, Wing Inspections
+:87Q0: Director, Complaints Resolution
+:88A0: Aide-de-camp
+:88B0: Protocol Officer
+:88C0: Sexual Assault Response Coordinator (SARC)
+:88I0: Innovation Officer
+:88M0: United States Air Force Medical Pinnacle Position
+:88X0: Operational STEM Officer
+:88Y0: Pathfinder Officer
+:89A0: Air Advisor (Basic)
+:89B0: Air Advisor (Basic) Team Leader
+:89C0: Air Advisor (Basic) Mission Commander
+:89D0: Air Advisor (Advanced)
+:89E0: Air Advisor (Advanced) Team Leader
+:89F0: Air Advisor (Advanced) Mission Commander
+:89G0: Combat Aviation Advisor
+:89H0: Combat Aviation Advisor Team Leader
+:89I0: Combat Aviation Advisor Mission Commander
+:89W0: Weapons of Mass Destruction Civil Support Team (WMD-CST)
+:90G0: General Officer
+:91C0: Commander
+:91E0: Wing Commander Equivalent
+:91W0: Wing Commander
+:92F0: Foreign Area Officer (FAO) Trainee
+:92J0: Non-designated Lawyer
+:92J1: AFROTC Educational Delay Law Student
+:92J2: Funded Legal Education Program Law Student
+:92J3: Excess Leave Law Student
+:92M0: Health Professions Scholarship Program (HPSP) Medical Student
+:92M1: Uniformed Services University of Health Sciences (USUHS) Student
+:92M2: HPSP Biomedical Science Student
+:92P0: Physician Assistant Student
+:92R0: Chaplain Candidate
+:92S0: Student Officer Authorization
+:92T0: Pilot Trainee
+:92T1: Combat Systems Officer Trainee
+:92T2: Air Battle Manager Trainee
+:92T3: Remotely Piloted Aircraft Pilot Trainee
+:92W0: Combat Wounded Warrior
+:92W1: Reserved for Future Use
+:92W2: Combat Wounded Warrior with Exemptions
+:92W3: Non-Combat Wounded Warrior
+:92W4: Wounded Warrior - Limited Assignment Status (LAS)
+:92W5: Wounded Warrior - Retired/Discharged
+:92W6: Reserved for Future Use
+:92W7: Reserved for Future Use
+:92W8: Wounded Warrior - Ambassador
+:92W9: Wounded Warrior - Project Planner/Officer
+:93P0: Patient
+:94N0: Nuclear Weapons Custodian
+:95A0: Non-EAD USAFR Academy Liaison Officer (ALO) or Civil Air Patrol Reserve Assistance
+  Program (CAPRAP) Officer
+:96A0: Disqualified Officer, Reasons Beyond Their Control
+:96B0: Disqualified Officer, Reasons Within Their Control
+:96D0: Officer Not Available for Use in Awarded AFSC for Cause
+:96U0: Unclassified Officer
+:96V0: Un-allotted
+:97E0: Executive Officer
+:99A0: Unspecified AFSC
+:99G0: Gold Bar Recruiter

data/lib/gov_codes/dafecd/shredout_acronyms.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GovCodes
+  module Dafecd
+    # Extracts shredout-level acronyms for the officer directory from two
+    # deterministic sources (both grounded verbatim in the record source):
+    #
+    #   a. Shredout TABLE values whose meaning ends in a trailing "(ACR)", e.g.
+    #      "Air Liaison Officer (ALO)" -> {U: "ALO"}. The :shredouts value is kept
+    #      verbatim; only the acronym is lifted out.
+    #
+    #   b. A numbered in-record enumeration of the form
+    #      "<family>X<shred> (<Title> (<ACR>))", e.g. in the 19Z record:
+    #      "19ZXB (Tactical Air Control Party Officer (TACPO))" -> {B: "TACPO"}.
+    #      Only codes belonging to the record's own specialty family are accepted.
+    module ShredoutAcronyms
+      # A shredout value's trailing parenthetical acronym.
+      TABLE_ACRONYM = /\(([A-Z][A-Z0-9]{1,7})\)\s*\z/
+
+      module_function
+
+      # @param shredouts [Hash{Symbol=>String}] parsed suffix => meaning
+      # @return [Hash{Symbol=>String}] suffix => trailing acronym
+      def from_table(shredouts)
+        result = {}
+        shredouts.each do |suffix, meaning|
+          match = meaning.match(TABLE_ACRONYM)
+          result[suffix] = match[1] if match
+        end
+        result
+      end
+
+      # @param record [String] the specialty record's source text
+      # @param family [String] the record's 3-char specialty family (e.g. "19Z")
+      # @return [Hash{Symbol=>String}] shred letter => acronym
+      def from_enumeration(record, family)
+        return {} if family.nil? || family.empty?
+        result = {}
+        pattern = /#{Regexp.escape(family)}X([A-Z])\s*\([^()]*\(([A-Z][A-Z0-9]{1,7})\)\)/
+        record.scan(pattern) do |shred, acronym|
+          result[shred.to_sym] = acronym
+        end
+        result
+      end
+    end
+  end
+end

data/lib/gov_codes/dafecd/shredout_degluer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module GovCodes
+  module Dafecd
+    # Applies verified de-glued shredout values.
+    #
+    # pdf-reader drops spaces inside shredout meanings exactly as it does inside
+    # specialty titles ("ImageryAnalyst", "TacticalAir Control Party Officer").
+    # The deterministic extractor keeps those verbatim and cannot safely re-insert
+    # the missing spaces. The clean values are produced out of band and shipped in
+    # per-publication files under shredout_overrides/ (mirroring title_overrides/).
+    #
+    # The data is nested one level deeper than the title overrides: a specialty
+    # maps to a suffix => clean-value map, e.g.
+    #
+    #   :1A1X8:
+    #     :A: C-32/C-40B/C Flight Attendant
+    #     :C: C-37A/B Flight Attendant
+    #
+    # The de-gluing invariant — enforced at build time by IndexBuilder — is that
+    # an override may only change SPACING and CASE relative to the raw extracted
+    # value; no letter, digit, or punctuation may change. Any drift (or an
+    # override targeting a shredout absent from the source) fails the build loudly
+    # rather than silently applying a stale value.
+    class ShredoutDegluer
+      # @return [ShredoutDegluer] loaded from +path+
+      def self.load(path)
+        overrides = YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+        new(overrides)
+      end
+
+      # @return [ShredoutDegluer] loaded from +publication+'s overrides file, or
+      #   an empty de-gluer when that file does not exist.
+      def self.for(publication)
+        path = publication.shredout_overrides_path
+        File.exist?(path) ? load(path) : empty
+      end
+
+      # An empty de-gluer applies no overrides (keeps the verbatim values).
+      def self.empty
+        new({})
+      end
+
+      # @param overrides [Hash{Symbol=>Hash{Symbol=>String}}] specialty =>
+      #   (suffix => clean value)
+      def initialize(overrides = {})
+        @overrides = overrides
+      end
+
+      # @return [Hash{Symbol=>String}, nil] suffix => clean value for +specialty+
+      def overrides_for(specialty)
+        @overrides[specialty]
+      end
+
+      # Yields every declared override so the build can verify each targets a
+      # shredout that actually exists (completeness gate).
+      def each_override
+        return enum_for(:each_override) unless block_given?
+        @overrides.each do |specialty, suffixes|
+          suffixes.each do |suffix, value|
+            yield specialty, suffix, value
+          end
+        end
+      end
+
+      def any?
+        !@overrides.empty?
+      end
+    end
+  end
+end

data/lib/gov_codes/dafecd/shredout_overrides/dafecd.yml

@@ -0,0 +1,27 @@
+# De-glued shredout values for DAFECD, effective 2025-10-31.
+# Each value is the source PDF shredout meaning with ONLY spacing/case
+# adjusted -- no letters, digits, or punctuation changed. Enforced at build
+# time: the IndexBuilder verifies each override against the raw extracted
+# shredout value (whitespace-and-case-insensitive equality) and fails the
+# build on drift or on an override targeting a shredout absent from the source.
+# Nested one level deeper than title_overrides: specialty => (suffix => value).
+:1A1X4:
+  :Z: Multi-domain Operations Aviator Data Mask
+:1A1X8:
+  :A: C-32/C-40B/C Flight Attendant
+  :C: C-37A/B Flight Attendant
+  :H: E-4B Flight Attendant
+:1D7X1:
+  :B: Systems Administration
+:1N1X1:
+  :A: Imagery Analyst
+:1N2X1:
+  :A: Electronic Non-Communications Analyst
+  :C: Signals Analyst
+:1P0X1:
+  :A: Ejection Seat Aircraft
+  :B: Non-Ejection Seat Aircraft
+:3F3X1:
+  :M: Management Engineering/Data Analytics
+:3P0X1:
+  :B: Combat Arms

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

@@ -0,0 +1,27 @@
+# De-glued shredout values for DAFOCD, effective 2025-10-31.
+# Each value is the source PDF shredout meaning with ONLY spacing/case
+# adjusted -- no letters, digits, or punctuation changed. Enforced at build
+# time: the IndexBuilder verifies each override against the raw extracted
+# shredout value (whitespace-and-case-insensitive equality) and fails the
+# build on drift or on an override targeting a shredout absent from the source.
+# Nested one level deeper than title_overrides: specialty => (suffix => value).
+:11UX:
+  :K: Instructor for weapon system designated by AFSC
+  :V: Automated Functional Applications Analyst
+:13BX:
+  :D: Mobile Air Control
+:13SX:
+  :E: Space Access and Sustainment
+:15WX:
+  :A: Advanced Weather Activities
+:17YX:
+  :A: Cyber Warfare Analyst
+  :D: Cyber Threat Defense Analyst
+  :O: Cyber Attack Operator
+:19ZX:
+  :B: Tactical Air Control Party Officer
+:44KX:
+  :N: Child Abuse
+:45BX:
+  :G: Replacement Arthroplasty
+  :J: Foot and Ankle Surgery

data/lib/gov_codes/dafecd/shredout_parser.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "patterns"
+require_relative "publication"
+
+module GovCodes
+  module Dafecd
+    # Parses a "Specialty Shredouts" table into a suffix => name map.
+    #
+    # The table is laid out in two side-by-side columns, e.g. (enlisted):
+    #
+    #     Suffix     Primary Aircraft            Suffix    Primary Aircraft
+    #        A       C-5 Flight Engineer            L      C-130H Flight Engineer
+    #        B       C-5 Loadmaster                 N      C-130H Loadmaster
+    #
+    # The officer directory uses the same two-column interleave under a different
+    # heading ("Suffix ... Portion of AFS to Which Related"). Both columns are
+    # captured. Values that wrap onto a continuation line are captured only up to
+    # the wrap (a documented, minor limitation). The table header is
+    # publication-specific (injected Publication); the default is enlisted.
+    class ShredoutParser
+      # A single suffix/name cell. The suffix is one capital letter followed by
+      # 2+ spaces; the name runs until 2+ spaces precede the next column's suffix
+      # or the line ends.
+      PAIR = /\b([A-Z])\s{2,}([A-Z0-9][A-Za-z0-9 \/().-]{2,45}?)(?=\s{2,}[A-Z]\s{2,}|\s*$)/
+
+      # A more permissive variant used by the RI/SDI extractor, whose values carry
+      # punctuation the AFSC tables never do: a colon ("8W1XX WSMs w/PAFSC: 2W0X1"
+      # in the Space Force 8W tables) and a comma ("Graduated, Flight Chief" in
+      # the 8R300 recruiter table). The AFSC ladder pipeline keeps the stricter
+      # PAIR (its default), so the shipped enlisted/officer artifacts are
+      # unaffected.
+      RI_SDI_PAIR = /\b([A-Z])\s{2,}([A-Z0-9][A-Za-z0-9 \/().:,-]{2,45}?)(?=\s{2,}[A-Z]\s{2,}|\s*$)/
+
+      def initialize(text, publication: Publication.dafecd, pair: PAIR)
+        @text = text
+        @header = publication.shredout_header
+        @pair = pair
+      end
+
+      # @return [Hash{Symbol=>String}] suffix letter => shredout name
+      def parse
+        result = {}
+        table_lines.each do |line|
+          # Strip stray decorative glyphs that would otherwise break the column
+          # lookahead (e.g. a U+F0EA bullet sitting in a between-column gap).
+          line.gsub(Patterns::DECORATIVE, " ").scan(@pair) do |suffix, name|
+            result[suffix.to_sym] = name.strip
+          end
+        end
+        result
+      end
+
+      private
+
+      # Lines belonging to the shredout table body: everything after the
+      # "Suffix ..." header up to a terminating boundary (a *NOTE, a numbered
+      # section, or the end of the given text).
+      def table_lines
+        lines = @text.lines
+        start = lines.index { |line| line.match?(@header) }
+        return [] if start.nil?
+
+        body = []
+        lines[(start + 1)..].each do |line|
+          stripped = line.strip
+          break if stripped.start_with?("*NOTE", "NOTE:")
+          break if stripped.match?(/\A\d+(?:\.\d+)*\.\s/)
+          body << line
+        end
+        body
+      end
+    end
+  end
+end