pubid 2.0.0.pre.alpha.49 → 2.0.0.pre.alpha.50

data/lib/pubid/iso/builder.rb

@@ -32,6 +32,15 @@ module Pubid
           return Identifiers::TcDocument
         end
 
+        # Bare TC reference (pubid-iso#285): "184/SC 4/WG 12 N10291" — the
+        # ISO/TC route without the ORIGINATOR prefix. tc_type is absent by
+        # construction; sc_type is the route's required segment and cannot
+        # appear on a standard identifier.
+        if parsed_hash[:sc_type] && parsed_hash[:tc_number]
+          parsed_hash[:tc_type] = "TC"
+          return Identifiers::TcDocument
+        end
+
         # An explicit document type (e.g. from a URN's `:tr:`/`:ts:` token) pins
         # the class regardless of the stage. The stage and type are separate URN
         # fields, but the stage is later folded into `:type_with_stage` (e.g.

data/lib/pubid/iso/parser.rb

@@ -29,7 +29,8 @@ module Pubid
       # TC documents must come first since they start with "ISO/"
       # and we need to distinguish them from regular ISO/IEC identifiers
       rule(:identifier) do
-        nsb_iso_identifier |
+        bare_tc_document |
+          nsb_iso_identifier |
           tc_document |
           directives_identifiers |
           jcgm_identifier |
@@ -62,6 +63,18 @@ module Pubid
           (str(":") >> year_digits.as(:year)).maybe
       end
 
+      # Bare TC document reference (pubid-iso#285): "184/SC 4/WG 12 N10291"
+      # — the ISO/TC route without the ORIGINATOR prefix; the builder
+      # canonicalizes the publisher to ISO. The SC segment is required so
+      # bare numbers cannot leak into the route.
+      rule(:bare_tc_document) do
+        digits.as(:tc_number) >>
+          str("/") >> sc_type >> space >> digits.as(:sc_number) >>
+          (str("/") >> wg_type >> space >> digits.as(:wg_number)).maybe >>
+          space >> str("N") >> space? >> digits.as(:number) >>
+          (str(":") >> year_digits.as(:year)).maybe
+      end
+
       rule(:tc_subcommittee_part) do
         # Full path: TC/SC 4/WG 3
         (str("/") >> sc_type >> space >> digits.as(:sc_number) >> str("/") >>

data/lib/pubid/nist/builder.rb

@@ -104,6 +104,16 @@ module Pubid
           identifier.part = letter_suffix_part
         end
 
+        # Part type "n" with a letter value — "NCSTAR 1nA" (pubid#555):
+        # the corpus rows carry part {type: "n", value: <letter>}, which
+        # renders as "n<letter>".
+        if parsed_hash[:n_letter_part]
+          identifier.part = Components::Part.new(
+            type: "n",
+            value: parsed_hash[:n_letter_part].to_s.sub(/\An/, "").upcase,
+          )
+        end
+
         # NEW: If we extracted an Edition from edition_dash_year, assign it now
         if edition_from_dash_year
           identifier.edition = edition_from_dash_year

data/lib/pubid/nist/caster.rb

@@ -729,6 +729,12 @@ module Pubid
           str_value = value.to_s.strip
           return nil if str_value.empty?
 
+          # The index suffix parses from both spellings ("index", "indx");
+          # the component's value is the long form either way, so
+          # parse(render(x)) == x for the CRPL-F-B corpus rows that print
+          # "indx" (pubid#557).
+          str_value = "index" if type == :index
+
           # For volume, create Volume component from string value
           # This handles patterns like "v1" that come from parser as simple strings
           if type == :volume

data/lib/pubid/nist/parser.rb

@@ -139,10 +139,18 @@ module Pubid
       # Single letter: any letter not followed by excluded keywords
       rule(:number_suffix) do
         (str("U") >> lower_letter) |
+          # n+UPPERCASE annex suffix (e.g., 1nA, 85nB — the BH/HR/NCSTAR/SP
+          # annex designations, pubid#555). Before the general letter branch,
+          # which would consume the lone "n" and strand the capital letter.
+          (str("n") >> upper_letter) |
           # An "r" directly followed by a digit is the revision marker (pubid#170),
           # not a suffix — leave it for the second_number/edition rules.
           # The guard sits before the letter so it tests the suffix start itself.
-          ((str("r") >> digit).absent? >> match("[a-zA-Z]") >> (
+          ((str("r") >> digit).absent? >> match("[a-zA-Z]") >>
+          # An uppercase letter following the suffix letter is the part
+          # type "n" + letter form ("1nA", pubid#555) — the suffix must
+          # stop so the parts rule can take the whole token.
+          match("[A-Z]").absent? >> (
           # Match suffixes
           str("ec") |
           str("ndex") |
@@ -438,9 +446,13 @@ module Pubid
             # Dash with letter suffix (e.g., 1-1A, 1-3B for NCSTAR, 73-197Ur for IR)
             # Must come before GCR pattern which expects another dash
             # Supports U+lowercase letter suffix (e.g., Ur, Ua, Ub-Uj for Unclassified variants)
+            # Supports n+UPPERCASE annex suffix (e.g., 1-1nA, 1-1nB — the BH/HR/NCSTAR
+            # annex designations, pubid#555): the n prefix lowercases to the same
+            # letter_suffix face as the plain letter
             # For other uppercase letters, only match single letter (A, B, C) to avoid consuming revision r
             (dash >> digits.as(:letter_base) >> (
               (str("U") >> lower_letter.as(:letter_suffix_extra)) |
+              (str("n") >> upper_letter.as(:letter_suffix_extra)) |
               upper_letter
             ).as(:letter_suffix)).as(:letter_number) |
             # Dash-SEPARATED letter suffix on a numbered part (e.g., 21-4-B,
@@ -669,6 +681,10 @@ module Pubid
         # Put more specific patterns first
         # CRITICAL: new_stage BEFORE language_code to avoid "ipd" being treated as translation
         new_stage |
+          # Part type "n" with a letter value — "NCSTAR 1nA" (pubid#555):
+          # the letter part suffixes the corpus renders as n<A> (Part
+          # type "n"); must precede the generic index/letter rules.
+          (str("n") >> upper_letter).as(:n_letter_part) |
           section | index | insert | appendix | pd_suffix |
           edition | date | legacy_edition | revision |
           version | # MOVED BEFORE volume - try dotted versions (v1.1) before simple volumes (v1)

data/lib/pubid/nist/series/base.rb

@@ -16,6 +16,16 @@ module Pubid
         # Return a cast hash, or nil to skip assignment.
         # Default: split letter suffix into a Part component.
         def self.cast_letter_number(value, _parsed_hash)
+          # The n+UPPERCASE annex capture (pubid#555, e.g., 800-85nB) arrives
+          # as a nested letter_suffix_extra: it casts to the n-notation Part
+          # (Part.new(type: "n", value: "B") renders "nB").
+          if value[:letter_suffix].is_a?(Hash)
+            letter = value[:letter_suffix][:letter_suffix_extra].to_s
+            return nil if letter.empty?
+
+            return { part: Components::Part.new(type: "n", value: letter.upcase) }
+          end
+
           full = combine_letter_suffix(value)
           return nil if full.nil? || full.empty?
 
@@ -47,8 +57,12 @@ module Pubid
         def self.finalize_identifier(_identifier, _parsed_hash); end
 
         # Combine `:letter_suffix` and `:letter_suffix_extra` (e.g., "U" + "r").
+        # The n+UPPERCASE annex capture nests the extra inside the suffix hash
+        # (pubid#555): unwrap it before stringifying.
         def self.combine_letter_suffix(value)
-          suffix = value[:letter_suffix].to_s.strip
+          suffix = value[:letter_suffix]
+          suffix = suffix[:letter_suffix_extra] if suffix.is_a?(Hash)
+          suffix = suffix.to_s.strip
           extra = value[:letter_suffix_extra].to_s.strip
           extra.empty? ? suffix : "#{suffix}#{extra}"
         end

data/lib/pubid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pubid
-  VERSION = "2.0.0.pre.alpha.49"
+  VERSION = "2.0.0.pre.alpha.50"
 end

data/lib/tasks/api_reference.rake

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "yard"
+
+namespace :docs do
+  # Generates docs/api-reference.md from the YARD registry over lib/ —
+  # the generated API reference the website assembles (pubid#577). CI
+  # regenerates and fails on drift, so the committed file cannot rot.
+  desc "Generate docs/api-reference.md from YARD"
+  task :api_reference do
+    require "pubid"
+    Pubid.eager_load_flavors!
+    YARD::Registry.clear
+    YARD::Parser::SourceParser.parse(Dir.glob("lib/**/*.rb").sort, [])
+
+    entry = lambda do |obj|
+      sig = obj.signature.to_s.strip.sub(/\Adef\s+/, "").gsub(/\s+/, " ")
+      doc = obj.docstring.strip.lines.first.to_s.strip
+      out = +"### `#{sig}`\n"
+      out << "\n#{doc}\n" unless doc.empty?
+      out
+    end
+
+    module_section = lambda do |path, names|
+      mod = YARD::Registry.at(path)
+      return "" unless mod
+
+      out = +"## `#{path}`\n\n"
+      names.sort.each do |name|
+        obj = mod.child("::#{name}") || mod.child(name.to_s)
+        out << entry.call(obj) if obj
+      end
+      out
+    end
+
+    out = +<<~HEADER
+      # API reference
+
+      <!-- Generated by `rake docs:api_reference` (YARD over lib/) — do not
+           edit by hand; CI fails on drift. The website assembles this file
+           into the library reference. -->
+
+    HEADER
+
+    out << module_section.call(
+      "Pubid",
+      %w[parse from_hash locate_stage locate_stage_flavors prefixes
+         prefix_flavors parse_by_prefix],
+    )
+    errors = YARD::Registry.at("Pubid::Errors")
+    if errors
+      out << "## `Pubid::Errors`\n\n"
+      errors.children
+        .select { |c| c.is_a?(YARD::CodeObjects::ClassObject) }
+        .sort_by(&:name).each do |klass|
+        sig = "Pubid::Errors::#{klass.name}"
+        sup = klass.superclass.to_s.split("::").last
+        doc = klass.docstring.strip.lines.first.to_s.strip
+        out << "### `#{sig} < #{sup}`\n"
+        out << "\n#{doc}\n" unless doc.empty?
+      end
+    end
+
+    Pubid::Registry.flavor_names.sort.each do |flavor|
+      mod = Pubid::Registry.get(flavor)
+      names = %w[parse parse_urn locate_stage locate_stage_by_harmonized_code
+                 locate_type prefixes all_typed_stages all_project_stages]
+        .select { |m| mod.respond_to?(m) }
+      out << module_section.call(mod.name, names)
+    end
+
+    id_klass = YARD::Registry.at("Pubid::Identifier")
+    if id_klass
+      out << "## `Pubid::Identifier` (instance methods)\n\n"
+      id_klass.meths(scope: :instance, inherited: false)
+        .select { |m| m.visibility == :public }
+        .sort_by(&:name).each do |obj|
+        out << entry.call(obj)
+      end
+    end
+
+    File.write("docs/api-reference.md", out)
+    puts "docs/api-reference.md: #{out.lines.count} lines, " \
+           "#{Pubid::Registry.flavor_names.size} flavors"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pubid
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.alpha.49
+  version: 2.0.0.pre.alpha.50
 platform: ruby
 authors:
 - Ribose Inc.
@@ -1048,6 +1048,7 @@ files:
 - lib/pubid/xsf/renderer.rb
 - lib/pubid/xsf/urn_generator.rb
 - lib/pubid/xsf/urn_parser.rb
+- lib/tasks/api_reference.rake
 - lib/tasks/benchmark.rake
 - lib/tasks/conformance.rake
 - lib/tasks/docs.rake