pubid 2.0.0.pre.alpha.9 → 2.0.0.pre.alpha.12

data/lib/pubid/renderers/directives_renderer.rb

@@ -37,7 +37,9 @@ module Pubid
           abbr = annotate(abbr, typed_stage_css(@id.typed_stage), 
                           annotated: ann)
         end
-        subgroup_str = @id.subgroup.render(context:) if @id.subgroup
+        if @id.subgroup
+          subgroup_str = render_component(@id.subgroup, context)
+        end
 
         [
           pub_str,
@@ -50,15 +52,15 @@ module Pubid
         ann = context.annotated
         parts = []
         if @id.number
-          parts << annotate(@id.number.render(context:), "docnumber",
+          parts << annotate(render_component(@id.number, context), "docnumber",
                             annotated: ann)
         end
         if @id.part
-          parts << " #{annotate(@id.part.render(context:), 'part', 
+          parts << " #{annotate(render_component(@id.part, context), 'part', 
                                 annotated: ann)}"
         end
         if @id.subpart
-          parts << "-#{annotate(@id.subpart.render(context:), 'part', 
+          parts << "-#{annotate(render_component(@id.subpart, context), 'part', 
                                 annotated: ann)}"
         end
         if @id.stage_iteration

data/lib/pubid/renderers/human_readable.rb

@@ -41,15 +41,15 @@ module Pubid
         ann = context.annotated
         parts = []
         if @id.number
-          parts << annotate(@id.number.render(context:), "docnumber",
+          parts << annotate(render_component(@id.number, context), "docnumber",
                             annotated: ann)
         end
         if @id.part
-          parts << "-#{annotate(@id.part.render(context:), 'part', 
+          parts << "-#{annotate(render_component(@id.part, context), 'part', 
                                 annotated: ann)}"
         end
         if @id.subpart
-          parts << "-#{annotate(@id.subpart.render(context:), 'part', 
+          parts << "-#{annotate(render_component(@id.subpart, context), 'part', 
                                 annotated: ann)}"
         end
         if @id.stage_iteration

data/lib/pubid/renderers/mr_string.rb

@@ -28,6 +28,20 @@ module Pubid
     class MrString < Base
       SEPARATOR_SUPPLEMENT = "_"
 
+      # The flat MR segments, in order, as the hook each one reads. A hook
+      # returning nil contributes no segment, so a flavor fills only the slots
+      # its identity actually uses — `mr_volume` (ECMA) is nil everywhere else.
+      SEGMENTS = %i[
+        mr_publisher
+        mr_type
+        mr_number_with_part
+        mr_year
+        mr_edition
+        mr_volume
+        mr_languages
+        mr_all_parts
+      ].freeze
+
       def render(context: nil, **)
         suffix = @id.mr_supplement_suffix
 
@@ -43,15 +57,7 @@ module Pubid
       private
 
       def render_flat(id)
-        parts = []
-        parts << id.mr_publisher
-        parts << id.mr_type
-        parts << id.mr_number_with_part
-        parts << id.mr_year
-        parts << id.mr_edition
-        parts << id.mr_languages
-        parts << id.mr_all_parts
-        parts.compact.join(".")
+        SEGMENTS.filter_map { |hook| id.public_send(hook) }.join(".")
       end
     end
   end

data/lib/pubid/renderers.rb

@@ -2,6 +2,7 @@
 
 module Pubid
   module Renderers
+    autoload :Annotator, "pubid/renderers/annotator"
     autoload :Base, "pubid/renderers/base"
     autoload :DirectivesRenderer, "pubid/renderers/directives_renderer"
     autoload :GuideRenderer, "pubid/renderers/guide_renderer"

data/lib/pubid/rendering/numbering.rb

@@ -4,21 +4,39 @@ module Pubid
   module Rendering
     module Numbering
       # Render number with optional parts and subparts
-      # @param number [Components::Code] primary number
-      # @param part [Components::Code, nil] optional part
-      # @param subpart [Components::Code, nil] optional subpart
+      # @param number [Components::Code, String, nil] primary number
+      # @param part [Components::Code, String, nil] optional part
+      # @param subpart [Components::Code, String, nil] optional subpart
       # @param options [Hash] rendering options
       # @return [String] formatted numbering string
       def render_numbering(number, part = nil, subpart = nil, **options)
-        return "" unless number&.value
+        number_str = numbering_value(number)
+        return "" unless number_str
 
-        result = " #{number.value}"
+        result = " #{number_str}"
         separator = options[:part_separator] || "-"
-        result += "#{separator}#{part.value}" if part&.value
-        result += "#{separator}#{subpart.value}" if subpart&.value
+        [part, subpart].each do |component|
+          value = numbering_value(component)
+          result += "#{separator}#{value}" if value
+        end
 
         result
       end
+
+      private
+
+      # `number`/`part`/`subpart` are a Components::Code on ::Pubid::Identifier
+      # but a plain :string in a growing number of flavors, so read the value
+      # through whichever shape the caller holds. Returns nil for an absent or
+      # empty component, which is what suppresses the segment.
+      def numbering_value(component)
+        return nil if component.nil?
+
+        value = component.respond_to?(:value) ? component.value : component
+        return nil if value.nil? || value.to_s.empty?
+
+        value.to_s
+      end
     end
   end
 end

data/lib/pubid/rendering.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pubid"
 module Pubid
   module Rendering
     autoload :Date, "pubid/rendering/date"

data/lib/pubid/sae/builder.rb

@@ -20,7 +20,7 @@ module Pubid
         when :type
           Components::Type.new(abbr: value.to_s)
         when :number
-          Components::Code.new(value: value.to_s)
+          value.to_s
         when :year
           { date: Components::Date.new(year: value.to_i) }
         else

data/lib/pubid/sae/identifiers/base.rb

@@ -7,15 +7,25 @@ module Pubid
     # Handles all SAE document types (AMS, AIR, ARP, AS, MA).
     class Identifier < ::Pubid::Identifier
       def self.parse(input)
+        unless input.is_a?(String)
+          raise Pubid::Errors::InvalidInputError,
+                Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+
+        if input.length > Pubid::MAX_INPUT_LENGTH
+          raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
+        end
+
         parsed = Parser.parse(input)
         Builder.build(parsed)
-      rescue Parslet::ParseFailed => e
-        raise "Failed to parse SAE identifier: #{input}\n#{e.message}"
       end
 
       attribute :publisher, :string, default: -> { "SAE" }
       attribute :type, Sae::Components::Type
-      attribute :number, Sae::Components::Code
+      # A plain :string, like every converted flavor. Sae::Components::Code was
+      # a bare alias of the shared component and never carried more than
+      # `value`, so this is a representation change only.
+      attribute :number, :string
       attribute :date, Sae::Components::Date
 
       def self.type

data/lib/pubid/sae/parser.rb

@@ -4,7 +4,7 @@ require "parslet"
 
 module Pubid
   module Sae
-    class Parser < Parslet::Parser
+    class Parser < ::Pubid::Parser::Grammar
       rule(:space) { str(" ") }
       rule(:digit) { match["0-9"] }
       rule(:digits) { digit.repeat(1) }

data/lib/pubid/sae/urn_generator.rb

@@ -12,7 +12,7 @@ module Pubid
       def urn_number
         return nil unless identifier.number
 
-        identifier.number.render(context: URN_CONTEXT)
+        identifier.number.to_s
       end
 
       def generate

data/lib/pubid/sae.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "pubid"
 module Pubid
   module Sae
     extend Pubid::PrefixesSupport

data/lib/pubid/schema/declaration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Schema
+    # A loaded flavor declaration (schema/{flavor}.yaml).
+    class Declaration
+      attr_reader :flavor, :schema_version, :prefixes, :identifier_types
+
+      def initialize(flavor:, schema_version:, prefixes:, identifier_types:)
+        @flavor = flavor
+        @schema_version = schema_version
+        @prefixes = prefixes.freeze
+        @identifier_types = identifier_types.map(&:freeze).freeze
+        freeze
+      end
+
+      # Own tokens plus joint/co-publication tokens from
+      # schema/core/joint_prefixes.yaml - mirrors the runtime
+      # Pubid::{Flavor}.prefixes contract (see PrefixesSupport).
+      def merged_prefixes
+        (prefixes + Loader.joint_prefixes_for(flavor)).freeze
+      end
+
+      def type_for(key)
+        identifier_types.find { |type| type.key == key }
+      end
+
+      def types_count
+        identifier_types.size
+      end
+    end
+  end
+end

data/lib/pubid/schema/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Schema
+    # Base error for schema loading and lookup failures.
+    class Error < StandardError; end
+
+    # Raised when a flavor declaration file cannot be found.
+    class NotFoundError < Error; end
+
+    # Raised when a declaration file violates the format contract.
+    class InvalidError < Error; end
+  end
+end

data/lib/pubid/schema/identifier_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Schema
+    # One identifier type declaration (e.g. iso "amendment", iec "vap").
+    class IdentifierType
+      attr_reader :key, :title, :short, :abbr, :typed_stages
+
+      def initialize(key:, title:, short: nil, abbr: [], typed_stages: [])
+        @key = key
+        @title = title
+        @short = short
+        @abbr = abbr.freeze
+        @typed_stages = typed_stages.map(&:freeze).freeze
+        freeze
+      end
+
+      def typed_stage_for_abbr(candidate)
+        typed_stages.find { |stage| stage.matches_abbr?(candidate) }
+      end
+    end
+  end
+end

data/lib/pubid/schema/loader.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Schema
+    # Loads and validates flavor declarations from schema/. Declarations
+    # are memoized and deeply frozen; loading is lazy per flavor so the
+    # parse hot path pays no boot cost.
+    class Loader
+      SCHEMA_ROOT = File.expand_path("../../../schema", __dir__).freeze
+      CORE_DIR = File.join(SCHEMA_ROOT, "core").freeze
+
+      class << self
+        def for(flavor)
+          flavor = flavor.to_s
+          declarations[flavor] ||= build_declaration(flavor)
+        end
+
+        def joint_prefixes_for(flavor)
+          joint_prefixes[flavor.to_s] || [].freeze
+        end
+
+        # Full joint-prefix map (flavor key => tokens) from
+        # schema/core/joint_prefixes.yaml.
+        def joint_prefixes_map
+          joint_prefixes
+        end
+
+        def loaded_flavors
+          declarations.keys.sort
+        end
+
+        private
+
+        def declarations
+          @declarations ||= {}
+        end
+
+        def joint_prefixes
+          @joint_prefixes ||= load_joint_prefixes
+        end
+
+        def load_joint_prefixes
+          path = File.join(CORE_DIR, "joint_prefixes.yaml")
+          data = YAML.safe_load_file(path)
+          data.fetch("joint_prefixes")
+            .transform_values(&:freeze)
+            .freeze
+        rescue Errno::ENOENT, KeyError => e
+          raise InvalidError, "cannot load #{path}: #{e.message}"
+        end
+
+        def build_declaration(flavor)
+          path = declaration_path(flavor)
+          data = YAML.safe_load_file(path)
+          validate!(flavor, path, data)
+          Declaration.new(
+            flavor: data.fetch("flavor"),
+            schema_version: data.fetch("schema_version"),
+            prefixes: data.fetch("prefixes"),
+            identifier_types: parse_identifier_types(data),
+          ).freeze
+        end
+
+        def declaration_path(flavor)
+          path = File.join(SCHEMA_ROOT, "#{flavor}.yaml")
+          unless File.exist?(path)
+            raise NotFoundError, "no declaration for #{flavor} at #{path}"
+          end
+
+          path
+        end
+
+        def parse_identifier_types(data)
+          data.fetch("identifier_types")
+            .map { |entry| parse_identifier_type(entry) }
+        end
+
+        def parse_identifier_type(entry)
+          IdentifierType.new(
+            key: entry.fetch("key"),
+            title: entry.fetch("title"),
+            short: entry["short"],
+            abbr: entry["abbr"] || [],
+            typed_stages: parse_typed_stages(entry),
+          )
+        end
+
+        def parse_typed_stages(entry)
+          (entry["typed_stages"] || []).map { |stage| parse_typed_stage(stage) }
+        end
+
+        def parse_typed_stage(stage)
+          TypedStage.new(
+            stage_code: stage.fetch("stage_code"),
+            type_code: stage["type_code"],
+            abbr: stage.fetch("abbr"),
+            name: stage["name"],
+            harmonized_stages: stage["harmonized_stages"] || [],
+          )
+        end
+
+        def validate!(flavor, path, data)
+          raise InvalidError, "#{path}: not a mapping" unless data.is_a?(Hash)
+
+          %w[flavor schema_version prefixes identifier_types].each do |key|
+            next if data.key?(key)
+
+            raise InvalidError, "#{path}: missing required key #{key}"
+          end
+          return unless data["flavor"] != flavor
+
+          raise InvalidError, "#{path}: flavor/file mismatch"
+        end
+      end
+    end
+  end
+end

data/lib/pubid/schema/typed_stage.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Schema
+    # One typed stage entry of an identifier type declaration.
+    class TypedStage
+      attr_reader :stage_code, :type_code, :abbr, :name, :harmonized_stages
+
+      def initialize(stage_code:, type_code: nil, abbr: [], name: nil,
+                     harmonized_stages: [])
+        @stage_code = stage_code
+        @type_code = type_code
+        @abbr = abbr.freeze
+        @name = name
+        @harmonized_stages = harmonized_stages.freeze
+        freeze
+      end
+
+      def matches_abbr?(candidate)
+        abbr.include?(candidate)
+      end
+    end
+  end
+end

data/lib/pubid/schema.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pubid
+  # Single source of truth declarations (schema/ directory). TODO 03 of the
+  # SSOT restructure: loader and value objects. TODO 04-07 make the runtime
+  # a consumer of these declarations (registry bridge, prefixes, metadata).
+  module Schema
+    autoload :Error, "pubid/schema/error"
+    autoload :NotFoundError, "pubid/schema/error"
+    autoload :InvalidError, "pubid/schema/error"
+    autoload :TypedStage, "pubid/schema/typed_stage"
+    autoload :IdentifierType, "pubid/schema/identifier_type"
+    autoload :Declaration, "pubid/schema/declaration"
+    autoload :Loader, "pubid/schema/loader"
+
+    class << self
+      # Pubid::Schema.for("iso") => frozen Pubid::Schema::Declaration
+      def for(flavor)
+        Loader.for(flavor)
+      end
+    end
+  end
+end

data/lib/pubid/tgpp/builder.rb

@@ -13,7 +13,7 @@ module Pubid
           suffix: data[:suffix]&.to_s,
           parts: extract_part_strings(data[:parts]),
           release: data[:release]&.to_s,
-          version: data[:version].to_s,
+          version: data[:version]&.to_s,
         )
       end
 

data/lib/pubid/tgpp/identifier.rb

@@ -14,7 +14,13 @@ module Pubid
       attribute :suffix, :string
       # 1–2 hyphen parts (e.g. "26.171-1", "29.198-04-1"); strings preserve any
       # zero-padding.
-      attribute :parts, :string, collection: true
+      # `initialize_empty` makes a part-less identifier hold `[]` on BOTH
+      # construction paths: Builder always passes an array, but the serialized
+      # hash carries no `parts` key, so from_hash used to leave it nil and the
+      # two compared unequal — which silently broke `#matches?` (and so every
+      # part-less relaton index lookup). It does not change the serialized
+      # shape: lutaml omits an empty collection either way. See CLAUDE.md.
+      attribute :parts, :string, collection: true, initialize_empty: true
       # Raw release token, stored verbatim: "REL-4", "Ph1", "UMTS",
       # "Release 2000".
       attribute :release, :string
@@ -73,18 +79,28 @@ module Pubid
         @with_publisher = false
       end
 
-      # Parse a 3GPP identifier string into an identifier object
+      # Parse a 3GPP identifier string into an identifier object.
+      #
+      # Let Parslet::ParseFailed propagate on a bad reference (matching ISO and
+      # ETSI), so relaton-cli's `rescue Parslet::ParseFailed` fetch handler
+      # catches it instead of a bare RuntimeError. The length guard keeps its
+      # ArgumentError — that is a different failure (input too long, not
+      # unparseable) and it is the ReDoS barrier.
+      #
       # @param identifier [String] The 3GPP identifier string to parse
       # @return [Identifier] The appropriate identifier object
       def self.parse(identifier)
+        unless identifier.is_a?(String)
+          raise Pubid::Errors::InvalidInputError,
+                Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+
         if identifier.length > Pubid::MAX_INPUT_LENGTH
-          raise ArgumentError, Pubid::INPUT_TOO_LONG_MESSAGE
+          raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
         end
 
         parsed = Parser.parse(identifier)
         Builder.build(parsed)
-      rescue Parslet::ParseFailed => e
-        raise "Failed to parse 3GPP identifier '#{identifier}': #{e.message}"
       end
     end
   end

data/lib/pubid/tgpp/identifiers/technical_report.rb

@@ -4,8 +4,8 @@ module Pubid
   module Tgpp
     module Identifiers
       # Technical Report identifier type.
-      # Format: [3GPP ]TR NN.NNN[suffix][-part…]:<release>/<version>
-      # Example: TR 00.01U:UMTS/3.0.0
+      # Format: [3GPP ]TR NN.NNN[suffix][-part…][:<release>][/<version>]
+      # Example: TR 00.01U:UMTS/3.0.0, or the partial "TR 00.01U".
       class TechnicalReport < Pubid::Tgpp::Identifier
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(

data/lib/pubid/tgpp/identifiers/technical_specification.rb

@@ -4,8 +4,8 @@ module Pubid
   module Tgpp
     module Identifiers
       # Technical Specification identifier type.
-      # Format: [3GPP ]TS NN.NNN[suffix][-part…]:<release>/<version>
-      # Example: TS 23.207:REL-4/2.0.0
+      # Format: [3GPP ]TS NN.NNN[suffix][-part…][:<release>][/<version>]
+      # Example: TS 23.207:REL-4/2.0.0, or the partial "TS 23.207".
       class TechnicalSpecification < Pubid::Tgpp::Identifier
         TYPED_STAGES = [
           Pubid::Components::TypedStage.new(

data/lib/pubid/tgpp/parser.rb

@@ -6,12 +6,18 @@ module Pubid
   module Tgpp
     # Parslet grammar for 3GPP identifiers.
     #
-    # Form: `[3GPP ]<TR|TS> <NN.NNN>[suffix][-part…]:<release>/<version>`
+    # Form: `[3GPP ]<TR|TS> <NN.NNN>[suffix][-part…][:<release>][/<version>]`
     #   TS 23.207:REL-4/2.0.0
     #   3GPP TR 00.01U:UMTS/3.0.0
     #   TS 29.198-04-1:REL-5/5.0.0
     #   TS 02.68:Release 2000/9.0.0
-    class Parser < Parslet::Parser
+    #   3GPP TS 23.207                (bare reference)
+    #
+    # The release and the version are both optional: a user reference names the
+    # document alone ("3GPP TS 23.207"), and relaton parses that bare form to
+    # search the index. Only the type and the dotted number core are required,
+    # so "TS" and "TS foo" are still rejected.
+    class Parser < ::Pubid::Parser::Grammar
       rule(:digit) { match["0-9"] }
       rule(:digits) { digit.repeat(1) }
       rule(:space) { str(" ") }
@@ -37,19 +43,29 @@ module Pubid
       # Excludes ":" (as well as "/") so the ":"-delimited URN scheme can always
       # encode it — every real release ("REL-4", "Ph1", "UMTS", "Release 2000")
       # is colon-free.
-      rule(:release) { match["^/:"].repeat(1).as(:release) }
+      #
+      # A trailing segment shaped exactly like a version is a mistyped "/"
+      # separator ("TS 23.207:2.0.0"), not a release: no release in the 88,464
+      # published index rows contains a dot at all. Reject it rather than
+      # silently misfiling the version as the release — which only became
+      # reachable once the version segment was made optional.
+      rule(:release) do
+        (version_core >> any.absent?).absent? >>
+          match["^/:"].repeat(1).as(:release)
+      end
 
       # Three-part version, kept as a string.
-      rule(:version) do
-        (digits >> str(".") >> digits >> str(".") >> digits).as(:version)
+      rule(:version_core) do
+        digits >> str(".") >> digits >> str(".") >> digits
       end
+      rule(:version) { version_core.as(:version) }
 
       rule(:identifier) do
         publisher_prefix.maybe >>
           type >> space >>
           number_core >> suffix.maybe >> parts >>
           (str(":") >> release).maybe >>
-          str("/") >> version
+          (str("/") >> version).maybe
       end
 
       rule(:root) { identifier }

data/lib/pubid/tgpp/renderer.rb

@@ -9,6 +9,7 @@ module Pubid
     #   "3GPP TS 23.207:REL-4/2.0.0"           (with_publisher: true)
     #   "TS 29.198-04-1:REL-5/5.0.0"           (parts)
     #   "TR 00.01U:UMTS/3.0.0"                 (suffix)
+    #   "TS 23.207"                            (partial reference)
     class Renderer < ::Pubid::Renderers::Base
       PUBLISHER = "3GPP"
 
@@ -17,15 +18,30 @@ module Pubid
         head = []
         head << PUBLISHER if with_publisher?(id)
         head << id.type_prefix
-        result = "#{head.join(' ')} #{id.code}"
-        # A handful of legacy records omit the release segment entirely
-        # (e.g. "TS 29.215/2.0.0").
-        result += ":#{id.release}" if id.release
-        "#{result}/#{id.version}"
+        "#{head.join(' ')} #{id.code}#{qualifiers(id)}"
       end
 
       private
 
+      # The trailing ":<release>" and "/<version>" qualifiers. Both are
+      # optional: a handful of legacy records omit the release entirely
+      # (e.g. "TS 29.215/2.0.0"), and a partial user reference omits both
+      # (e.g. "TS 23.207"). Render no separator for an absent one.
+      #
+      # Blank, not just nil: the grammar cannot produce "", but a hand-built
+      # hash can, and a dangling "TS 23.207:" would not re-parse. This mirrors
+      # the same guard in UrnGenerator#tail_segments.
+      def qualifiers(id)
+        result = +""
+        result << ":#{id.release}" unless blank?(id.release)
+        result << "/#{id.version}" unless blank?(id.version)
+        result
+      end
+
+      def blank?(value)
+        value.nil? || value.empty?
+      end
+
       # Default is no publisher token (the relaton index id form); the caller
       # opts in via `to_s(with_publisher: true)`.
       def with_publisher?(id)