pubid 1.15.21 → 2.0.0.alpha.10

data/lib/pubid/ieee/compaction.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    # Serialization compaction for IEEE hashes — a recursive transform hooked
+    # into Ieee::Identifier#to_hash (collapse) and .from_hash (expand). Two
+    # compactions, both provably lossless and nested-safe (they descend into a
+    # Corrigendum `base` too):
+    #
+    # 1. **typed_stage -> `stage` scalar.** The multi-field `typed_stage` object
+    #    becomes a single `stage` key holding its canonical abbreviation,
+    #    rebuilt from the TYPED_STAGES registry. The abbreviation keys the
+    #    registry uniquely, and the collapse fires only when the registry's
+    #    reconstruction is byte-identical to the serialized sub-hash — an
+    #    unrecognised / non-matching stage is left as the full object (fails
+    #    closed).
+    #
+    # 2. **`draft` slash strip.** `Components::Draft#to_s` renders `"/D3"`; the
+    #    leading `/` is boilerplate, so the serialized form is `"D3"`. No expand
+    #    step is needed — `Draft.parse` already accepts the slashless form and
+    #    reproduces `"/D3"` (verified across the whole corpus), so from_hash and
+    #    rendering are unchanged.
+    #
+    # A recursive hash transform (rather than lutaml attributes) is deliberate:
+    # `stage` collides with the inherited `Components::Stage` attribute name (a
+    # redefinition would reintroduce the multi-flavor nondeterminism we hit with
+    # `number`), and only a whole-hash walk reaches a nested Corrigendum `base`,
+    # which a per-object `to_hash` override cannot (the nested-serialization
+    # wall). The runtime `typed_stage`/`draft_obj` objects are untouched.
+    module Compaction
+      module_function
+
+      # abbr => canonical serialized typed_stage sub-hash, mirroring what the
+      # parent serializer + canonicalizer emit (nils dropped, and a default
+      # `project_status: false` dropped). Memoized.
+      def sub_hash_for(abbr)
+        (@sub_hash_for ||= build_sub_hash_map)[abbr]
+      end
+
+      def build_sub_hash_map
+        TypedStages::TYPED_STAGES.to_h { |ts| [ts.abbr.first, entry_sub_hash(ts)] }
+      end
+
+      # NB: this must list every Components::TypedStage attribute. If a field is
+      # added there but not here, the collapse guard fails closed — affected
+      # stages stay full objects (still lossless) but stop compacting; extend
+      # this list to keep them compact.
+      def entry_sub_hash(typed_stage)
+        {
+          "abbr" => typed_stage.abbr,
+          "stage_code" => typed_stage.stage_code,
+          "type_code" => typed_stage.type_code,
+          "iso_stage_equivalent" => typed_stage.iso_stage_equivalent,
+          "ieee_draft_equivalent" => typed_stage.ieee_draft_equivalent,
+          "approval_status" => typed_stage.approval_status,
+          "project_status" => typed_stage.project_status || nil,
+        }.compact
+      end
+
+      # Recursively compact every hash in the tree: collapse a reproducible
+      # `typed_stage` to a `stage` scalar and strip the leading `/` off `draft`.
+      def collapse(node)
+        collapse_hash(node) if node.is_a?(::Hash)
+        node.each { |v| collapse(v) } if node.is_a?(::Array)
+        node
+      end
+
+      def collapse_hash(node)
+        collapse_stage(node)
+        draft = node["draft"]
+        node["draft"] = draft.delete_prefix("/") if draft.is_a?(::String)
+        node.each_value { |v| collapse(v) }
+      end
+
+      # Collapse only when the registry rebuilds the exact same sub-hash, so no
+      # information is ever lost.
+      def collapse_stage(node)
+        ts = node["typed_stage"]
+        abbr = ts["abbr"]&.first if ts.is_a?(::Hash)
+        return unless abbr && sub_hash_for(abbr) == ts
+
+        node.delete("typed_stage")
+        node["stage"] = abbr
+      end
+
+      # Inverse of {collapse} for `stage`: replace a recognised `stage` scalar
+      # with its registry typed_stage sub-hash so lutaml rebuilds the component
+      # (nested bases included). `draft` needs no expansion — Draft.parse
+      # accepts the slashless form. An unrecognised value is left alone.
+      def expand(node)
+        expand_hash(node) if node.is_a?(::Hash)
+        node.each { |v| expand(v) } if node.is_a?(::Array)
+        node
+      end
+
+      def expand_hash(node)
+        key = stage_key(node)
+        sub = sub_hash_for(node[key].to_s) if key
+        if sub
+          node.delete(key)
+          node["typed_stage"] = deep_dup(sub)
+        end
+        node.each_value { |v| expand(v) }
+      end
+
+      def stage_key(node)
+        return :stage if node.key?(:stage)
+
+        "stage" if node.key?("stage")
+      end
+
+      def deep_dup(node)
+        case node
+        when ::Hash then node.transform_values { |v| deep_dup(v) }
+        when ::Array then node.map { |v| deep_dup(v) }
+        else node
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ieee/components/code.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Ieee
+    module Components
+      # IEEE document code (number with parts/subparts)
+      # Handles formats like:
+      #   802          - simple numbers
+      #   802.15.4     - dotted parts
+      #   C57.12.00    - prefix with parts
+      #   11073-10404  - dashed parts
+      #
+      # Stays independent of Pubid::Components::Code because IEEE tracks
+      # +original_separator+ to round-trip dot vs dash notation, and uses
+      # +number+ rather than +value+.
+      class Code < Lutaml::Model::Serializable
+        attribute :prefix, :string             # C, P for some identifiers
+        attribute :number, :string             # Main number (802, 1234, etc.)
+        attribute :parts, :string, collection: true # Array of part strings
+        attribute :original_separator, :string # Original separator (. or -) from parsing
+
+        def initialize(prefix: nil, number: nil, parts: nil,
+original_separator: nil)
+          super()
+          self.prefix = prefix
+          self.number = number
+          self.parts = parts || []
+          self.original_separator = original_separator
+        end
+
+        # Parse code string into components
+        def self.parse(code_str)
+          return nil if code_str.nil? || code_str.empty?
+
+          # Extract prefix if present (C, P)
+          prefix_match = code_str.match(/^([A-Z])/)
+          prefix = prefix_match ? prefix_match[1] : nil
+
+          # Remove prefix for number parsing
+          remainder = prefix ? code_str[prefix.length..] : code_str
+
+          # Detect the separator used
+          separator = nil
+          if remainder.include?(".")
+            separator = "."
+          elsif remainder.include?("-")
+            separator = "-"
+          end
+
+          # Split by dots or dashes to get number and parts
+          components = remainder.split(/[.-]/)
+          number = components.shift
+
+          new(
+            prefix: prefix,
+            number: number,
+            parts: components.empty? ? nil : components,
+            original_separator: separator,
+          )
+        end
+
+        def to_s
+          result = ""
+          result += prefix if prefix
+          result += number if number # Guard against nil number (e.g., "ANSI X")
+
+          if parts && !parts.empty?
+            # Use original separator if available
+            if original_separator
+              separator = original_separator
+            elsif prefix == "P" || (!prefix && parts.first && parts.first.length > 3)
+              # Fallback to heuristics when original separator unknown
+              # Determine separator based on prefix and pattern:
+              # - Letter prefix (C, etc.) codes use dots: C37.111
+              # - P-prefix codes typically use dashes: P11073-10404
+              # - Pure numeric codes with 5+ digits use dashes: 61523-4 (IEC style)
+              # - Traditional IEEE codes like 802.11 use dots
+              #
+              # Heuristic:
+              # 1. P-prefix or long part (>3 chars) → dash
+              # 2. Letter prefix (except P) → dot
+              # 3. Long number (5+ digits) → dash (IEC pattern)
+              # 4. Default → dot (traditional IEEE)
+              separator = "-"
+            elsif prefix && prefix != "P"
+              separator = "."
+            elsif !prefix && number && number.length >= 5
+              separator = "-"
+            else
+              # Default to dot for traditional IEEE codes like 802.11
+              separator = "."
+            end
+
+            parts.each do |part|
+              result += separator + part
+            end
+          end
+
+          result
+        end
+
+        def render(context: nil)
+          to_s
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ieee/components/draft.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Ieee
+    module Components
+      # IEEE draft version
+      # Handles formats like:
+      #   /D5              - version only
+      #   /D3.4            - version with revision
+      #   /D7, July 2019   - with date
+      class Draft < Lutaml::Model::Serializable
+        attribute :version, :string       # D5, D3, etc.
+        attribute :revision, :string      # .4, .2 in D3.4
+        attribute :year, :string
+        attribute :month, :string
+        attribute :day, :string
+        attribute :original_month, :string # Store original month format
+        attribute :comma_before_month, :boolean, default: -> {
+          false
+        } # Track if comma was in input
+
+        # Month name to number mapping
+        MONTH_NAMES = {
+          "January" => "1", "February" => "2", "March" => "3", "April" => "4",
+          "May" => "5", "June" => "6", "July" => "7", "August" => "8",
+          "September" => "9", "October" => "10", "November" => "11", "December" => "12",
+          "Jan" => "1", "Feb" => "2", "Mar" => "3", "Apr" => "4",
+          "Jun" => "6", "Jul" => "7", "Aug" => "8", "Sep" => "9", "Sept" => "9",
+          "Oct" => "10", "Nov" => "11", "Dec" => "12"
+        }.freeze
+
+        def initialize(version: nil, revision: nil, year: nil, month: nil,
+day: nil)
+          super()
+          self.version = version
+          self.revision = revision
+          self.year = year
+          self.original_month = month # Store original format
+          self.month = convert_month(month)
+          self.day = day
+        end
+
+        # Month names as an alternation, longest-first so "September" wins over
+        # "Sep"; each may carry a trailing period ("Sept."). Used to split a
+        # rendered draft's trailing date back out.
+        MONTH_ALTERNATION =
+          MONTH_NAMES.keys.sort_by { |m| -m.length }
+            .map { |m| "#{Regexp.escape(m)}\\.?" }.join("|").freeze
+        private_constant :MONTH_ALTERNATION
+
+        DATE_SUFFIX =
+          /(?:(, | )(#{MONTH_ALTERNATION})(?: (\d{1,2}))?(?:, | )| )((?:19|20)\d{2}[a-z]{0,2})\z/
+        private_constant :DATE_SUFFIX
+
+        # Parse a rendered draft such as "/D3", "/D3.4", "/D7 Jul 2019", or a
+        # bare "D5"/"5" back into a Draft. This is the exact inverse of #to_s:
+        # `Draft.parse(d.to_s).to_s == d.to_s` must hold, because the identifier
+        # stores the draft as its rendered string and rebuilds the object with
+        # this method after `from_hash` (a mismatch breaks `to_hash` round-trip).
+        # @param value [String, Draft] the value to coerce
+        # @return [Draft]
+        def self.parse(value)
+          return value if value.is_a?(Draft)
+
+          body = strip_prefix(value.to_s)
+          version, month, day, year, comma = split_date(body)
+          draft = new(version: version, month: month, day: day, year: year)
+          draft.comma_before_month = comma
+          draft
+        end
+
+        # Remove the leading "/D" (or a bare leading "D"/"/") that #to_s emits,
+        # leaving the version and any trailing date.
+        def self.strip_prefix(str)
+          return str[2..] if str.start_with?("/D")
+          return str[1..] if str.start_with?("/")
+          return str[1..] if str.start_with?("D") && str.length > 1
+
+          str
+        end
+        private_class_method :strip_prefix
+
+        # Split a trailing rendered date off the version, so the version stays
+        # clean (the SI/PSI renderer reads `draft_obj.version` directly). Returns
+        # [version, month, day, year, comma_before_month].
+        def self.split_date(body)
+          m = body.match(DATE_SUFFIX)
+          return [body, nil, nil, nil, false] unless m
+
+          version = body[0...m.begin(0)]
+          # The leading group is nil for the month-less " YEAR" form.
+          comma = m[1] == ", "
+          [version, m[2], m[3], m[4], comma]
+        end
+        private_class_method :split_date
+
+        # Convert month name to numeric value
+        def convert_month(month_name)
+          return nil unless month_name
+
+          MONTH_NAMES[month_name] || month_name
+        end
+
+        # Access the numeric month value
+        def numeric_month
+          month
+        end
+
+        def to_s
+          result = "/D#{version}"
+          result += ".#{revision}" if revision
+
+          if year
+            # Use original month format to preserve abbreviated vs full names
+            display_month = original_month
+
+            if display_month
+              # Use comma_before_month flag if set, otherwise detect from month format
+              use_comma_before = if defined?(@comma_before_month) && !@comma_before_month.nil?
+                                   @comma_before_month
+                                 else
+                                   # Default: Full month names have comma, abbreviated don't
+                                   display_month.length > 4 && display_month != "Sept"
+                                 end
+
+              result += use_comma_before ? ", #{display_month}" : " #{display_month}"
+              result += " #{day}" if day
+
+              # Abbreviated months: " Year", Full months: ", Year"
+              result += if display_month.length <= 4 || display_month == "Sept"
+                          " #{year}"
+                        else
+                          ", #{year}"
+                        end
+            else
+              result += " #{year}"
+            end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ieee/components/relationship.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# IEEE's Relationship component is now the shared Pubid::Components::Relationship.
+# This subclass exists so existing references (Pubid::Ieee::Components::Relationship,
+# the VALID_TYPES constants, etc.) continue to resolve without rewriting every
+# call site.
+module Pubid
+  module Ieee
+    module Components
+      class Relationship < ::Pubid::Components::Relationship; end
+    end
+  end
+end

data/lib/pubid/ieee/components/typed_stage.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Pubid
+  module Ieee
+    module Components
+      # TypedStage combines type and stage information for IEEE identifiers
+      # Following the proven ISO/IEC/CEN/BSI pattern
+      #
+      # IEEE has unique requirements:
+      # - Draft stages (D1-D9) with different approval levels
+      # - "P" (Project) prefix for drafts only
+      # - ISO stage equivalents for joint development (ISO/IEC/IEEE)
+      # - Bidirectional format conversion capability
+      #
+      # Key IEEE stage distinctions:
+      # - Unapproved Draft: Working drafts (D1-D6)
+      # - Approved Draft: Board-approved but unpublished (D7-D9)
+      # - Published: Final standards (no P prefix)
+      class TypedStage < Lutaml::Model::Serializable
+        # All recognized abbreviations for this stage
+        # First in array is canonical abbreviation
+        attribute :abbr, :string, collection: true
+
+        # IEEE-specific stage code
+        # Values: published, working_draft, committee_draft, draft_standard,
+        #         final_draft, preliminary, new_proposal
+        attribute :stage_code, :string
+
+        # Document type code
+        # Values: standard, draft
+        attribute :type_code, :string
+
+        # ISO stage equivalent for joint development (optional)
+        # Values: PWI, NP, WD, CD, DIS, FDIS, or nil
+        attribute :iso_stage_equivalent, :string
+
+        # IEEE draft notation equivalent (optional)
+        # Values: D1, D2-D3, D4-D6, D7-D9, P, or nil
+        attribute :ieee_draft_equivalent, :string
+
+        # Approval status
+        # Values: unapproved, approved, published
+        attribute :approval_status, :string
+
+        # Whether "P" (Project) prefix applies
+        # true for all draft stages, false for published
+        attribute :project_status, :boolean, default: -> { false }
+
+        # Convert to IEEE format representation
+        # @return [String] IEEE format abbreviation
+        def to_ieee_format
+          return abbr.first unless project_status
+
+          ieee_draft_equivalent || "P"
+        end
+
+        # Convert to ISO format representation
+        # @return [String] ISO format stage code
+        def to_iso_format
+          iso_stage_equivalent || abbr.first
+        end
+
+        # Get canonical abbreviation (first in list)
+        # @return [String] canonical abbreviation
+        def canonical_abbreviation
+          abbr.first
+        end
+
+        # Check if this is a draft stage
+        # @return [Boolean] true if draft, false if published
+        def draft?
+          project_status || approval_status != "published"
+        end
+
+        # Check if board-approved
+        # @return [Boolean] true if approved or published
+        def approved?
+          ["approved", "published"].include?(approval_status)
+        end
+
+        # Get display name for stage
+        # @return [String] human-readable stage name
+        def name
+          case stage_code
+          when "published" then "Published Standard"
+          when "working_draft" then "Working Draft"
+          when "committee_draft" then "Committee Draft"
+          when "draft_standard" then "Draft Standard"
+          when "final_draft" then "Final Draft"
+          when "preliminary" then "Preliminary Work Item"
+          when "new_proposal" then "New Work Item Proposal"
+          else stage_code.to_s.split("_").map(&:capitalize).join(" ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ieee/identifier.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Pubid::Ieee::Identifier is the IEEE base class (a real Pubid::Identifier
+# subclass); IEEE builds its identifiers as instances of it directly. Its body and `.parse` live in
+# identifiers/base.rb. This file just ensures it is loaded.

data/lib/pubid/ieee/identifiers/adopted_standard.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    module Identifiers
+      # Adopted Standard Identifier
+      # IEEE's adoption of another organization's standard
+      # Example: "IEEE Standard No 18-1968 (ANSI C55.1-1968)"
+      # This means IEEE adopted ANSI's standard C55.1-1968 as their Std No 18-1968
+      class AdoptedStandard < Identifier
+        # IEEE's identifier for this adopted standard.
+        #
+        # Typed as the cross-flavor base `::Pubid::Identifier` (not the
+        # IEEE-only `Identifier`) so serialization never rejects a cross-flavor
+        # value. lutaml enforces the declared attribute type; `polymorphic:
+        # true` permits only *subclasses* of it, and a `Pubid::Ansi::…` /
+        # `Pubid::Iec::…` object is not a subclass of `Pubid::Ieee::Identifier`.
+        # The cross-flavor child carries its own `_type`, so `from_hash` routes
+        # it back via `TypeResolver`.
+        attribute :ieee_identifier, ::Pubid::Identifier, polymorphic: true
+
+        # Original identifiers from ANSI/ASME/ISO/IEC/etc (array for multi-part
+        # adoptions). Cross-flavor by design: an `IEEE Std <n> (ANSI <m>)`
+        # adoption stores a `Pubid::Ansi::…` object here. See `ieee_identifier`
+        # above for why this must be `::Pubid::Identifier`, not IEEE-only.
+        attribute :adopted_identifiers, ::Pubid::Identifier, polymorphic: true,
+                                              collection: true
+
+        def publisher
+          ieee_identifier&.publisher || "IEEE"
+        end
+
+        # An adoption names one document by two designations and carries no
+        # number of its own, so `root.number` — the key relaton-index sorts and
+        # bsearches on — was "". Walk to the IEEE designation, which is the one
+        # IEEE files the document under, and which is also the source of truth
+        # for `publisher` above.
+        def root
+          ieee_identifier ? ieee_identifier.root : self
+        end
+
+        # The document number must reach the URN and the MR slug too, not only
+        # `#root` — the project rule that an identity-bearing marker reaches
+        # every identity surface. `UrnGenerator#code_component` and the base
+        # `mr_number_with_part` both read `code_obj`, which a wrapper does not
+        # have, so all 66 adoptions collapsed onto 5 URNs and 5 slugs — and
+        # `to_slug` is an output FILENAME, so that is 66 documents overwriting
+        # each other. Delegate to the IEEE designation, as `#root` does.
+        #
+        # `code_obj` is a plain attr_accessor on the base, not a lutaml
+        # attribute, so overriding it as a method is safe here.
+        def code_obj
+          ieee_identifier&.code_obj
+        end
+
+        # Likewise the year: without it "AIEE No 15-1944" and "AIEE No 15-1959"
+        # — two different documents — produced the same slug "aiee.std.15".
+        # This is the `mr_year` HOOK, not a `#year` method: `year` is a lutaml
+        # attribute on the base, and a method of that name would shadow the
+        # generated accessor (the CLAUDE.md landmine).
+        def mr_year
+          (year || ieee_identifier&.year)&.to_s
+        end
+
+        # `publisher` is *derived* from `ieee_identifier` (the serialized source
+        # of truth), so it must not be serialized. Emitting it breaks the
+        # canonical round-trip: the derived value is default-omitted on the parse
+        # path (publisher unset), but re-emitted after from_hash materializes the
+        # attribute default (the override then returns ieee_identifier.publisher,
+        # e.g. "AIEE", not the "IEEE" default). Drop it — ieee_identifier rebuilds
+        # it. (AdoptedStandard is always a top-level wrapper, never nested, so a
+        # to_hash-level drop is sufficient — same as JointDevelopment.)
+        def to_hash(*args)
+          hash = super
+          hash.delete("publisher") if hash.is_a?(::Hash)
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/pubid/ieee/identifiers/amendment.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Ieee
+    module Identifiers
+      # Amendment identifier for IEEE standards
+      # Represents additions/changes to a published standard
+      # Example: IEEE Std 802.3-2018/Amd 4-2020
+      class Amendment < SupplementIdentifier
+        # The amendment's own ordinal (`number`) and `year` — uniform names,
+        # not `amd_number`/`amd_year`. `number` is a plain string redefining the
+        # inherited Components::Code (leaf-safe, like the standards); `year` is
+        # the inherited base :string. `root.number` still returns the *base*
+        # document number, so the index key is unaffected. Mirrors Corrigendum.
+        attribute :number, :string
+        # `year` inherited from the base.
+
+        # TYPED_STAGES for amendment
+        # Amendment uses "Amd" abbreviation
+        TYPED_STAGES = [
+          Components::TypedStage.new(
+            abbr: ["Amd"],
+            type_code: "amendment",
+            stage_code: "published",
+          ),
+        ].freeze
+
+        # MR supplement suffix: `amd.{number}.{year}` (e.g. "/amd.4.2020").
+        # The MrString renderer recurses into `base` and appends this so the
+        # full IEEE amendment round-trips losslessly (mirrors Corrigendum).
+        def mr_supplement_suffix
+          segments = ["amd"]
+          segments << number.to_s if number
+          segments << year.to_s if year
+          segments.join(".")
+        end
+      end
+    end
+  end
+end