gov_codes 0.1.1 → 0.1.2

data/lib/gov_codes/afsc/releases/dafocd/2025-10-31/ri.yml

@@ -0,0 +1,193 @@
+# DAFOCD Reporting Identifiers (RI) + Special Duty Identifiers (SDI)
+# Source: DAFOCD 31 Oct 25 v3.pdf
+# Directory: Department of the Air Force Officer Classification Directory
+# Effective date: 2025-10-31  (v3)
+# Generated deterministically by bin/extract_afsc_from_pdf.rb.
+# Do not edit by hand; re-run the extractor against the source PDF.
+# Titles are de-glued via human-verified overrides (spacing/case only, gated
+# against the verbatim source); a title without an override is kept verbatim.
+---
+:80C0:
+  :name: Commander, Cadet Squadron, USAF Academy
+  :changed_date: '2022-10-31'
+:81C0:
+  :name: Instructor, Officer Training School
+  :changed_date: '2019-04-30'
+:81D0:
+  :name: Air Force Reserve Officer Training Corps Detachment Commander and Professor
+    of Aerospace Studies
+  :changed_date: '2020-04-30'
+:81L0:
+  :name: Education and Training Leader
+  :changed_date: '2020-04-30'
+:81T0:
+  :name: Instructor
+:82A0:
+  :name: Academic Program Manager
+:83R0:
+  :name: Recruiting Service
+:84H0:
+  :name: Historian
+  :changed_date: '2024-10-31'
+:85G0:
+  :name: Honor Guard
+  :changed_date: '2025-10-31'
+:86M0:
+  :name: Operations Management
+:86P0:
+  :name: Command and Control
+:87G0:
+  :name: Wing Inspector General
+  :changed_date: '2018-04-30'
+:87I0:
+  :name: Director, Wing Inspections
+  :changed_date: '2012-10-31'
+:87Q0:
+  :name: Director, Complaints Resolution
+  :changed_date: '2012-10-31'
+:88A0:
+  :name: Aide-de-camp
+:88B0:
+  :name: Protocol Officer
+  :changed_date: '2019-10-31'
+:88C0:
+  :name: Sexual Assault Response Coordinator (SARC)
+  :acronym: SARC
+  :changed_date: '2020-04-30'
+:88I0:
+  :name: Innovation Officer
+  :changed_date: '2022-10-31'
+:88M0:
+  :name: United States Air Force Medical Pinnacle Position
+  :changed_date: '2024-04-30'
+:88X0:
+  :name: Operational STEM Officer
+  :changed_date: '2024-10-31'
+:88Y0:
+  :name: Pathfinder Officer
+  :changed_date: '2023-10-31'
+:89A0:
+  :name: Air Advisor (Basic)
+  :changed_date: '2022-10-31'
+:89B0:
+  :name: Air Advisor (Basic) Team Leader
+  :changed_date: '2022-10-31'
+:89C0:
+  :name: Air Advisor (Basic) Mission Commander
+  :changed_date: '2022-10-31'
+:89D0:
+  :name: Air Advisor (Advanced)
+  :changed_date: '2022-10-31'
+:89E0:
+  :name: Air Advisor (Advanced) Team Leader
+  :changed_date: '2022-10-31'
+:89F0:
+  :name: Air Advisor (Advanced) Mission Commander
+  :changed_date: '2022-10-31'
+:89G0:
+  :name: Combat Aviation Advisor
+  :changed_date: '2025-04-30'
+:89H0:
+  :name: Combat Aviation Advisor Team Leader
+  :changed_date: '2025-04-30'
+:89I0:
+  :name: Combat Aviation Advisor Mission Commander
+  :changed_date: '2025-04-30'
+:89W0:
+  :name: Weapons of Mass Destruction Civil Support Team (WMD-CST)
+  :changed_date: '2020-10-31'
+:90G0:
+  :name: General Officer
+:91C0:
+  :name: Commander
+:91E0:
+  :name: Wing Commander Equivalent
+:91W0:
+  :name: Wing Commander
+:92F0:
+  :name: Foreign Area Officer (FAO) Trainee
+:92J0:
+  :name: Non-designated Lawyer
+:92J1:
+  :name: AFROTC Educational Delay Law Student
+:92J2:
+  :name: Funded Legal Education Program Law Student
+:92J3:
+  :name: Excess Leave Law Student
+:92M0:
+  :name: Health Professions Scholarship Program (HPSP) Medical Student
+:92M1:
+  :name: Uniformed Services University of Health Sciences (USUHS) Student
+:92M2:
+  :name: HPSP Biomedical Science Student
+:92P0:
+  :name: Physician Assistant Student
+  :changed_date: '2017-10-31'
+:92R0:
+  :name: Chaplain Candidate
+:92S0:
+  :name: Student Officer Authorization
+:92T0:
+  :name: Pilot Trainee
+:92T1:
+  :name: Combat Systems Officer Trainee
+:92T2:
+  :name: Air Battle Manager Trainee
+:92T3:
+  :name: Remotely Piloted Aircraft Pilot Trainee
+:92W0:
+  :name: Combat Wounded Warrior
+  :changed_date: '2015-05-11'
+:92W1:
+  :name: Reserved for Future Use
+  :changed_date: '2015-05-11'
+:92W2:
+  :name: Combat Wounded Warrior with Exemptions
+  :changed_date: '2015-05-11'
+:92W3:
+  :name: Non-Combat Wounded Warrior
+  :changed_date: '2015-05-11'
+:92W4:
+  :name: Wounded Warrior - Limited Assignment Status (LAS)
+  :acronym: LAS
+  :changed_date: '2015-05-11'
+:92W5:
+  :name: Wounded Warrior - Retired/Discharged
+  :changed_date: '2015-05-11'
+:92W6:
+  :name: Reserved for Future Use
+  :changed_date: '2015-05-11'
+:92W7:
+  :name: Reserved for Future Use
+  :changed_date: '2015-05-11'
+:92W8:
+  :name: Wounded Warrior - Ambassador
+  :changed_date: '2019-10-31'
+:92W9:
+  :name: Wounded Warrior - Project Planner/Officer
+  :changed_date: '2019-10-31'
+:93P0:
+  :name: Patient
+:94N0:
+  :name: Nuclear Weapons Custodian
+:95A0:
+  :name: Non-EAD USAFR Academy Liaison Officer (ALO) or Civil Air Patrol Reserve Assistance
+    Program (CAPRAP) Officer
+:96A0:
+  :name: Disqualified Officer, Reasons Beyond Their Control
+:96B0:
+  :name: Disqualified Officer, Reasons Within Their Control
+:96D0:
+  :name: Officer Not Available for Use in Awarded AFSC for Cause
+:96U0:
+  :name: Unclassified Officer
+:96V0:
+  :name: Un-allotted
+:97E0:
+  :name: Executive Officer
+:99A0:
+  :name: Unspecified AFSC
+  :changed_date: '2015-04-20'
+:99G0:
+  :name: Gold Bar Recruiter
+  :changed_date: '2013-06-05'

data/lib/gov_codes/afsc/releases.rb

@@ -0,0 +1,219 @@
+require "date"
+require "yaml"
+
+module GovCodes
+  module AFSC
+    # Loads the versioned release manifest and per-release specialty index for a
+    # publication (DAFECD enlisted, DAFOCD officer), and resolves the release in
+    # effect on a given date. Both publications share this resolve/merge/cache
+    # machinery and are resolved independently (their release dates may diverge).
+    #
+    # See docs/plans/2026-07-08-afsc-pdf-representation-design.md
+    # "Versioning by document release".
+    #
+    # Storage layout (per release):
+    #   lib/gov_codes/afsc/releases.yml                          # manifest
+    #   lib/gov_codes/afsc/releases/dafecd/<date>/enlisted.yml   # enlisted index
+    #   lib/gov_codes/afsc/releases/dafocd/<date>/officer.yml    # officer index
+    #
+    # Resolution: releases are sorted ascending by effective_date. A given
+    # `as_of` resolves to the release with the greatest effective_date <= as_of;
+    # `as_of: nil` resolves it as of today. A release only takes effect on its
+    # own effective_date -- a release dated in the future (e.g. one a consumer
+    # pre-loads ahead of its official date, see DEC-004 below) is not resolved
+    # until that date arrives, even though it is the most recently added one. A
+    # date before the earliest shipped release resolves to no release (an empty
+    # index / nil date).
+    #
+    # Extensibility (DEC-004): both tiers merge across the load path (gem lib dir
+    # first, then the load path). The manifest's per-publication release list is
+    # unioned by effective_date -- a consumer releases.yml ADDS releases without
+    # hiding the shipped ones, and a same-date entry from the load path wins. For
+    # the resolved release, the release index found at each lookup path is merged,
+    # so a consumer may drop gov_codes/afsc/releases/dafecd/<date>/enlisted.yml to
+    # extend or override the shipped index.
+    module Releases
+      # Publication key for the enlisted directory (DAFECD).
+      ENLISTED_PUBLICATION = "dafecd"
+      # Publication key for the officer directory (DAFOCD).
+      OFFICER_PUBLICATION = "dafocd"
+
+      class << self
+        def manifest(lookup: $LOAD_PATH)
+          manifest_cache[cache_key(lookup)] ||= load_manifest(lookup)
+        end
+
+        def enlisted_index(as_of: nil, lookup: $LOAD_PATH)
+          release_index(ENLISTED_PUBLICATION, "enlisted.yml", as_of: as_of, lookup: lookup)
+        end
+
+        def officer_index(as_of: nil, lookup: $LOAD_PATH)
+          release_index(OFFICER_PUBLICATION, "officer.yml", as_of: as_of, lookup: lookup)
+        end
+
+        # Resolve the RI/SDI index for +publication+ (enlisted DAFECD or officer
+        # DAFOCD). RI/SDI codes live in both directories with different code
+        # grammars (5-char enlisted, 4-char officer), so this wrapper is
+        # parameterized by publication; it otherwise reuses the same resolve/
+        # merge/cache and acronym-overlay machinery as enlisted_index/
+        # officer_index.
+        def ri_index(as_of: nil, lookup: $LOAD_PATH, publication: ENLISTED_PUBLICATION)
+          release_index(publication, "ri.yml", as_of: as_of, lookup: lookup)
+        end
+
+        # Resolve the effective date for +publication+ (defaults to enlisted).
+        # Publications are resolved independently: an officer release date never
+        # moves the enlisted latest date and vice versa.
+        def effective_date_for(as_of: nil, lookup: $LOAD_PATH, publication: ENLISTED_PUBLICATION)
+          release = resolve_release(publication, as_of: as_of, lookup: lookup)
+          release && release[:date]
+        end
+
+        def reset!
+          @manifest_cache = {}
+          @index_cache = {}
+        end
+
+        private
+
+        def manifest_cache
+          @manifest_cache ||= {}
+        end
+
+        def index_cache
+          @index_cache ||= {}
+        end
+
+        def cache_key(lookup)
+          Array(lookup).dup
+        end
+
+        def to_date(as_of)
+          return nil if as_of.nil?
+          return as_of if as_of.is_a?(Date)
+          Date.parse(as_of.to_s)
+        rescue Date::Error
+          raise ArgumentError,
+            "invalid as_of #{as_of.inspect}: expected a Date or a parseable date string (e.g. \"2025-10-31\")"
+        end
+
+        # Ordered list of directories to search: the gem lib dir first, then the
+        # provided lookup path. Deduplicated to avoid loading the same file twice.
+        def lookup_paths(lookup)
+          gem_lib_dir = File.expand_path("../..", __dir__)
+          ([gem_lib_dir] + Array(lookup)).uniq
+        end
+
+        # Resolve, merge, and cache the release index for +publication+. Always
+        # resolves the release first (cheap: the manifest itself is cached) and
+        # keys the expensive part -- loading and merging the index file -- on
+        # the RESOLVED release's date, not the raw +as_of+. With `as_of: nil`
+        # meaning "today," keying on the raw input would freeze the cache to
+        # whichever release happened to be current at the first call and never
+        # notice a later release's effective_date arrive.
+        def release_index(publication, index_file, as_of:, lookup:)
+          release = resolve_release(publication, as_of: as_of, lookup: lookup)
+          return {} unless release
+
+          key = [publication, index_file, release[:date], cache_key(lookup)]
+          index_cache[key] ||= load_release_index(release, publication, index_file, lookup)
+        end
+
+        def resolve_release(publication, as_of:, lookup:)
+          releases = release_list(lookup, publication)
+          return nil if releases.empty?
+
+          target = to_date(as_of) || Date.today
+          releases.reverse.find { |r| r[:date] <= target }
+        end
+
+        # Releases for +publication+ from the manifest, each annotated with a
+        # parsed :date and the :dir name used to locate its index, sorted
+        # ascending by date.
+        def release_list(lookup, publication)
+          entries = manifest(lookup: lookup)[publication.to_sym] || []
+          entries.filter_map do |entry|
+            raw = entry[:effective_date]
+            next unless raw
+
+            date = raw.is_a?(Date) ? raw : Date.parse(raw.to_s)
+            dir = raw.is_a?(Date) ? raw.strftime("%Y-%m-%d") : raw.to_s
+            entry.merge(date: date, dir: dir)
+          end.sort_by { |r| r[:date] }
+        end
+
+        def load_manifest(lookup)
+          merged = {}
+          each_yaml(lookup, ["gov_codes", "afsc", "releases.yml"]) do |data|
+            merge_manifest!(merged, data)
+          end
+          merged
+        end
+
+        def load_release_index(release, publication, index_file, lookup)
+          merged = {}
+          parts = ["gov_codes", "afsc", "releases", publication, release[:dir], index_file]
+          each_yaml(lookup, parts) { |data| merged.merge!(data) }
+          apply_acronym_overlay(merged, publication, release, lookup)
+          merged
+        end
+
+        # Apply the consumer acronym overlay (Task 3, "dedicated tier"): a flat
+        # SPECIALTY => ACRONYM map at releases/<pub>/<dir>/acronyms.yml, resolved
+        # for the SAME release as the index and merged across the load path
+        # (consumer-loaded-last wins). Applied ONLY to specialties already in the
+        # index, so it sets an entry's :acronym without ever replacing the entry
+        # (the index merge above is shallow — overlaying whole entries here would
+        # drop name/skill_levels/shredouts). The consumer overlay wins over the
+        # source-extracted acronym shipped in the index. The gem ships no
+        # acronyms.yml; an absent overlay leaves the index unchanged. Resolved per
+        # release, so overlays never leak across document dates or publications.
+        def apply_acronym_overlay(merged, publication, release, lookup)
+          overlay = {}
+          parts = ["gov_codes", "afsc", "releases", publication, release[:dir], "acronyms.yml"]
+          each_yaml(lookup, parts) { |data| overlay.merge!(data) }
+          overlay.each do |specialty, acronym|
+            entry = merged[specialty]
+            entry[:acronym] = acronym if entry
+          end
+        end
+
+        # Merge a manifest hash into +acc+. Per-publication release lists are
+        # unioned by effective_date (a same-date entry from a later-loaded file
+        # wins); non-list values fall back to a plain overwrite.
+        def merge_manifest!(acc, incoming)
+          incoming.each do |publication, releases|
+            acc[publication] = if acc[publication].is_a?(Array) && releases.is_a?(Array)
+              union_releases(acc[publication], releases)
+            else
+              releases
+            end
+          end
+          acc
+        end
+
+        def union_releases(base, overrides)
+          by_date = {}
+          (base + overrides).each do |entry|
+            by_date[entry[:effective_date]] = entry if entry.is_a?(Hash)
+          end
+          by_date.values
+        end
+
+        # Yield each parsed YAML hash found at +parts+ across the lookup paths,
+        # skipping missing files and malformed YAML (graceful degradation).
+        def each_yaml(lookup, parts)
+          lookup_paths(lookup).each do |dir|
+            path = File.join(dir, *parts)
+            next unless File.exist?(path)
+
+            data = YAML.load_file(path, symbolize_names: true)
+            yield data if data.is_a?(Hash)
+          rescue Psych::SyntaxError, TypeError
+            next
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gov_codes/afsc/releases.yml

@@ -0,0 +1,11 @@
+---
+:dafecd:
+- :effective_date: '2025-10-31'
+  :version_label: v3.5
+  :source: DAFECD -31 October 25 v3.5 FINAL.pdf
+  :name: Department of the Air Force Enlisted Classification Directory
+:dafocd:
+- :effective_date: '2025-10-31'
+  :version_label: v3
+  :source: DAFOCD 31 Oct 25 v3.pdf
+  :name: Department of the Air Force Officer Classification Directory