@pubid/pubid 0.1.23 → 0.1.25

package/dist/flavors/iso/grammar.js

@@ -118,6 +118,14 @@ function buildRules() {
     rule("tc_type", () => literalAlternation(TC_TYPES).as("tc_type"));
     rule("sc_type", () => str("SC/QC").or(str("SC")).as("sc_type"));
     rule("wg_type", () => literalAlternation(WG_TYPES).as("wg_type"));
+    // Bare TC reference (pubid-iso#285): "184/SC 4/WG 12 N10291" — the
+    // ISO/TC route without the ORIGINATOR prefix; the SC segment is
+    // required so bare numbers cannot leak into the route.
+    rule("bare_tc_document", () => digits.as("tc_number")
+        .then(str("/"), rules["sc_type"], space, digits.as("sc_number"))
+        .then(str("/"), rules["wg_type"], space, digits.as("wg_number")).maybe()
+        .then(space, str("N"), space.maybe(), digits.as("number"))
+        .then(str(":"), yearDigits.as("year")).maybe());
     rule("tc_subcommittee_part", () => str("/")
         .then(rules["sc_type"], space, digits.as("sc_number"), str("/"), rules["wg_type"], space, digits.as("wg_number"))
         .or(str("/").then(rules["sc_type"], space, digits.as("sc_number"))));
@@ -200,7 +208,7 @@ function buildRules() {
         .as("base")
         .then(space.maybe(), str("|"), space.maybe(), rules["idf_identifier"])
         .as("joint_identifier"));
-    rule("identifier", () => rules["nsb_iso_identifier"].or(rules["tc_document"], rules["directives_identifiers"], rules["jcgm_identifier"], rules["iso_r_supplement_identifier"], rules["iso_r_identifier"], rules["supplement_supplement_supplement_identifier"], rules["supplement_supplement_identifier"], rules["supplement_identifier"], rules["joint_identifier"], rules["identifier_copublishers"]));
+    rule("identifier", () => rules["bare_tc_document"].or(rules["nsb_iso_identifier"], rules["tc_document"], rules["directives_identifiers"], rules["jcgm_identifier"], rules["iso_r_supplement_identifier"], rules["iso_r_identifier"], rules["supplement_supplement_supplement_identifier"], rules["supplement_supplement_identifier"], rules["supplement_identifier"], rules["joint_identifier"], rules["identifier_copublishers"]));
     rule("root", () => rules["identifier"]);
     return rules;
 }

package/dist/flavors/iso/index.js

@@ -147,6 +147,13 @@ class IsoBuilder {
         }
         if (tree["supplements"] !== undefined)
             return this.buildBundled(tree);
+        // Bare TC reference (pubid-iso#285): tc_type is absent by
+        // construction; sc_type is the route's required segment and cannot
+        // appear on a standard identifier. Canonicalizes the publisher to ISO.
+        if (tree["tc_type"] === undefined && tree["sc_type"] !== undefined && tree["tc_number"] !== undefined) {
+            tree["tc_type"] = "TC";
+            return this.buildTc(tree);
+        }
         if (tree["tc_type"] !== undefined)
             return this.buildTc(tree);
         return this.buildStandard(tree);
@@ -499,12 +506,25 @@ function parseIsoUrn(urn) {
             else
                 supp.number = parts.shift();
         }
-        if ((parts[0] ?? "").startsWith("v")) {
-            const version = parts.shift().slice(1);
-            supp.number = version.split(".")[0];
-        }
+        // The legacy year-overloaded wire ("amd:2007:v2" -- the number rode
+        // the version slot): a v-token with no preceding number carries the
+        // NUMBER. The RFC 5141-bis order ("amd:1:2007:v2") keeps the number
+        // in its own slot, so a v-token after a number is the true
+        // <supplversion>.
+        const consumeV = () => {
+            if ((parts[0] ?? "").startsWith("v")) {
+                const value = parts.shift().slice(1).split(".")[0];
+                if (supp.number === undefined)
+                    supp.number = value;
+                else
+                    supp.version = value;
+            }
+        };
+        consumeV();
         if (supp.year === undefined && /^\d{4}$/.test(parts[0] ?? ""))
             supp.year = parts.shift();
+        // a v-token after the year would otherwise start a type-less wrap
+        consumeV();
         if (parts[0] !== undefined && !/^\d+$/.test(parts[0]) &&
             !/^(amd|cor|sup|add|v\d+|stage-)/i.test(parts[0])) {
             supp.languages = parts.shift().split(",").map((l) => l.toUpperCase()).join("/");
@@ -570,10 +590,16 @@ function parseIsoUrn(urn) {
         }
         const suppTree = {};
         if (supp.stage !== undefined) {
-            const stage = ISO_TYPED_STAGES.find((s) => s.stageCode === supp.stage);
+            // A harmonized code resolves within the supplement's own type
+            // family -- the IS-family default would turn a staged Corrigendum
+            // into a plain IS (mirrors the gem's build_identifier).
+            const stage = /^\d\d\.\d\d$/.test(supp.stage)
+                ? ISO_TYPED_STAGES.find((st) => st.harmonized?.includes(supp.stage) && st.typeKey === supp.type) ??
+                    ISO_TYPED_STAGES.find((st) => st.harmonized?.includes(supp.stage) && st.typeKey === "is")
+                : ISO_TYPED_STAGES.find((st) => st.stageCode === supp.stage);
             suppTree["type_with_stage"] = stage !== undefined
                 ? stage.abbr[0] ?? ""
-                : supp.stage.toUpperCase();
+                : supp.type?.toUpperCase() ?? supp.stage.toUpperCase();
         }
         if (supp.type !== undefined && suppTree["type_with_stage"] === undefined) {
             suppTree["type_with_stage"] = supp.type.toUpperCase();
@@ -582,6 +608,8 @@ function parseIsoUrn(urn) {
             suppTree["number"] = supp.number;
         if (supp.year !== undefined)
             suppTree["date"] = supp.year;
+        if (supp.version !== undefined)
+            suppTree["supplement_version"] = supp.version;
         if (supp.languages !== undefined)
             suppTree["languages"] = supp.languages;
         tree = { base: tree, ...suppTree };

package/dist/flavors/iso/model.js

@@ -465,14 +465,9 @@ class IsoUrnGenerator extends BaseUrnGenerator {
         const stageCode = ts.entry.stageCode;
         if (stageCode === "published")
             return undefined;
-        const typeKey = id.typeKey();
-        const combinedKey = typeKey !== "is" ? `${stageCode}${typeKey}` : stageCode;
-        const stageAbbrUrn = TYPED_STAGE_MAP[combinedKey] ?? TYPED_STAGE_MAP[stageCode];
-        if (stageAbbrUrn !== undefined) {
-            if (id.stage_iteration !== undefined)
-                return `${stageAbbrUrn}.${id.stage_iteration.render() ?? ""}`;
-            return stageAbbrUrn;
-        }
+        // RFC 5141 carries the stage as the harmonized code only; the typed
+        // abbreviations live in the human face. Legacy abbreviation URNs are
+        // accepted on ingestion and re-canonicalized here.
         const harmonized = ts.entry.harmonized;
         if (harmonized === undefined || harmonized.length === 0)
             return undefined;
@@ -558,17 +553,15 @@ class IsoUrnGenerator extends BaseUrnGenerator {
                 parts.push(stageComp);
             parts.push(supp.typeKey() === "suppl" || supp.typeKey() === "add" ? "sup" : supp.typeKey());
             const iter = supp.typeKey() === "suppl" || supp.stage_iteration === undefined ? undefined : supp.stage_iteration.render();
+            // RFC 5141 supplement slots in order: number, year (the bis
+            // additive extension), then the published version.
+            if (supp.number !== undefined)
+                parts.push(supp.number);
             const d = urnDate(supp);
-            if (d !== undefined) {
+            if (d !== undefined)
                 parts.push(d);
-                if (supp.number !== undefined)
-                    parts.push(iter !== undefined ? `v${supp.number}.${iter}` : `v${supp.number}`);
-            }
-            else {
-                if (supp.number !== undefined)
-                    parts.push(supp.number);
-                parts.push(iter !== undefined ? `v1.${iter}` : "v1");
-            }
+            const version = supp.supplement_version ?? 1;
+            parts.push(iter !== undefined ? `v${version}.${iter}` : `v${version}`);
             if (supp.languages !== undefined && supp.languages.length > 0) {
                 parts.push(supp.languages.map((l) => l.code).join(","));
             }
@@ -616,10 +609,14 @@ const supplementPublisherMappings = () => [
         },
     },
 ];
-const SUPPLEMENT_MAPPINGS = keyValue(...ISO_MAPPINGS, ...supplementPublisherMappings(), stageMapping(), { wire: "base", to: "base" });
+const SUPPLEMENT_MAPPINGS = keyValue(...ISO_MAPPINGS, ...supplementPublisherMappings(), stageMapping(), { wire: "base", to: "base" }, 
+// omitted when unset, so parsed human faces keep their hashes
+{ wire: "supplement_version", to: "supplement_version" });
 export class IsoSupplementIdentifier extends IsoSingleIdentifier {
     static attributes = extendAttributes(IsoSingleIdentifier, {
         base: { type: IsoIdentifier },
+        // The RFC 5141 <supplversion> (corrected version of the supplement).
+        supplement_version: { type: "string" },
     });
     static mappings = SUPPLEMENT_MAPPINGS;
     render() {

package/dist/flavors/nist/index.js

@@ -301,6 +301,14 @@ function cast(type, value, h, policy, series = "") {
         }
         case "part_number":
             return s(value);
+        case "n_letter_part": {
+            // Part type "n" with a letter value (pubid#555): the "1nA" /
+            // "1-1nA" annex tokens capture whole, the caster strips the n.
+            const v = s(value);
+            if (v === undefined)
+                return undefined;
+            return { part: new NistPart({ type: "n", value: v.replace(/^n/, "").toUpperCase() }) };
+        }
         case "letter_number": {
             if (!isObj(value))
                 return undefined;
@@ -413,6 +421,11 @@ function cast(type, value, h, policy, series = "") {
         case "appendix":
         case "errata":
         case "index":
+            // The component's value is the long form either way (pubid#584):
+            // both spellings parse, the render prints the abbreviated indx.
+            if (s(value) === "indx")
+                return "index";
+            return s(value);
         case "insert":
             return s(value);
         case "revision": {

package/dist/model/identifier.d.ts

@@ -56,6 +56,8 @@ export declare abstract class BaseIdentifier {
     /** Ruby to_urn: the flavor's UrnGenerator, else the base template. */
     toUrn(): string;
     fromHash(hash: Record<string, unknown>): BaseIdentifier;
+    /** SubsetMatch: an all-parts reference skips the part attributes. */
+    subsetAllPartsWildcard(): boolean;
     protected classAttributes(): AttributeTable;
     /** Wire key for an attribute: custom mapping or the attribute name. */
     protected wireKeyFor(name: string): {

package/dist/model/identifier.js

@@ -104,6 +104,10 @@ export class BaseIdentifier {
     fromHash(hash) {
         return this.constructor.fromHash(hash);
     }
+    /** SubsetMatch: an all-parts reference skips the part attributes. */
+    subsetAllPartsWildcard() {
+        return Boolean(this["all_parts"]);
+    }
     classAttributes() {
         return this.constructor.attributes;
     }

package/dist/model/subset-match.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Subset match: `subsetMatch(reference, candidate)` — the TypeScript port of
+ * Pubid::SubsetMatch (lib/pubid/subset_match.rb), the semantics behind Ruby's
+ * `Identifier#===`.
+ *
+ * The match is true when every part that `reference` states matches
+ * `candidate`. A part the reference leaves nil or empty is a wildcard. The
+ * operator is NOT symmetric: the receiver is the reference (`ISO 9001` is
+ * matched by `ISO 9001:2015`, not the other way round).
+ *
+ * Rules (see the Ruby module for the normative docs):
+ * - Both objects must be of the same concrete class; a reference never falls
+ *   back to the base document of a wrapper.
+ * - A default value is stated: `ISO 9001` (published stage) does not match
+ *   `ISO/DIS 9001`.
+ * - A collection matches by position, and the reference may be shorter
+ *   (`ISO/IEC 9001` matches `ISO/IEC/IEEE 9001`; `ISO/IEEE 9001` does not).
+ * - A STRICT attribute (class `subsetStrict` declaration) is exempt from the
+ *   wildcards: the reference always states it, a stated collection must match
+ *   in full, and nested matches run in BOTH directions with the class's own
+ *   rule.
+ * - A reference with `allParts` set skips part/parts/subpart/allParts.
+ * - Nested identifiers and components recurse with their own match; every
+ *   other value compares with deep scalar equality.
+ */
+import { BaseIdentifier } from "./identifier.js";
+import { Component } from "./component.js";
+/** One attribute: theirs satisfies the reference value mine. */
+export declare function valueMatch(mine: unknown, theirs: unknown): boolean;
+/** Strict attributes compare exactly, composing nested matches both ways. */
+export declare function exactMatch(mine: unknown, theirs: unknown): boolean;
+/**
+ * True when `candidate` holds every part that `reference` states. Both must
+ * be identifiers or components of the same concrete class.
+ */
+export declare function subsetMatch(reference: BaseIdentifier | Component, candidate: unknown): boolean;

package/dist/model/subset-match.js

@@ -0,0 +1,133 @@
+/**
+ * Subset match: `subsetMatch(reference, candidate)` — the TypeScript port of
+ * Pubid::SubsetMatch (lib/pubid/subset_match.rb), the semantics behind Ruby's
+ * `Identifier#===`.
+ *
+ * The match is true when every part that `reference` states matches
+ * `candidate`. A part the reference leaves nil or empty is a wildcard. The
+ * operator is NOT symmetric: the receiver is the reference (`ISO 9001` is
+ * matched by `ISO 9001:2015`, not the other way round).
+ *
+ * Rules (see the Ruby module for the normative docs):
+ * - Both objects must be of the same concrete class; a reference never falls
+ *   back to the base document of a wrapper.
+ * - A default value is stated: `ISO 9001` (published stage) does not match
+ *   `ISO/DIS 9001`.
+ * - A collection matches by position, and the reference may be shorter
+ *   (`ISO/IEC 9001` matches `ISO/IEC/IEEE 9001`; `ISO/IEEE 9001` does not).
+ * - A STRICT attribute (class `subsetStrict` declaration) is exempt from the
+ *   wildcards: the reference always states it, a stated collection must match
+ *   in full, and nested matches run in BOTH directions with the class's own
+ *   rule.
+ * - A reference with `allParts` set skips part/parts/subpart/allParts.
+ * - Nested identifiers and components recurse with their own match; every
+ *   other value compares with deep scalar equality.
+ */
+import { BaseIdentifier } from "./identifier.js";
+import { Component } from "./component.js";
+/** Attributes an all-parts reference does not restrict. */
+const ALL_PARTS_ATTRIBUTES = ["part", "parts", "subpart", "allParts"];
+function isSubsetMatchable(v) {
+    return v instanceof BaseIdentifier || v instanceof Component;
+}
+/** True for undefined/null and for an empty string or collection. */
+function blank(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === "string")
+        return value === "";
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+/**
+ * Exact equality for non-identifier values: scalars by identity, plain
+ * objects and arrays structurally (Ruby's `==` on the lutaml values).
+ */
+function scalarEqual(mine, theirs) {
+    if (mine === theirs)
+        return true;
+    if (Array.isArray(mine) && Array.isArray(theirs)) {
+        return mine.length === theirs.length && mine.every((v, i) => scalarEqual(v, theirs[i]));
+    }
+    if (Array.isArray(mine) || Array.isArray(theirs))
+        return false;
+    if (mine !== null && theirs !== null &&
+        typeof mine === "object" && typeof theirs === "object") {
+        const a = mine;
+        const b = theirs;
+        const keys = Object.keys(a);
+        if (keys.length !== Object.keys(b).length)
+            return false;
+        return keys.every((k) => k in b && scalarEqual(a[k], b[k]));
+    }
+    return false;
+}
+/** A shorter reference collection matches the leading elements. */
+function collectionMatch(mine, theirs) {
+    if (!Array.isArray(theirs))
+        return false;
+    return mine.length <= theirs.length && mine.every((v, i) => valueMatch(v, theirs[i]));
+}
+/** A strict collection matches in full, never as a prefix. */
+function exactCollectionMatch(mine, theirs) {
+    if (!Array.isArray(theirs))
+        return false;
+    return mine.length === theirs.length && mine.every((v, i) => exactMatch(v, theirs[i]));
+}
+/** One attribute: theirs satisfies the reference value mine. */
+export function valueMatch(mine, theirs) {
+    if (blank(mine))
+        return true;
+    if (Array.isArray(mine))
+        return collectionMatch(mine, theirs);
+    if (isSubsetMatchable(mine))
+        return subsetMatch(mine, theirs);
+    return scalarEqual(mine, theirs);
+}
+/** Strict attributes compare exactly, composing nested matches both ways. */
+export function exactMatch(mine, theirs) {
+    if (blank(mine) && blank(theirs))
+        return true;
+    if (Array.isArray(mine))
+        return exactCollectionMatch(mine, theirs);
+    if (isSubsetMatchable(mine)) {
+        return subsetMatch(mine, theirs) && isSubsetMatchable(theirs) && subsetMatch(theirs, mine);
+    }
+    return scalarEqual(mine, theirs);
+}
+/**
+ * True when `candidate` holds every part that `reference` states. Both must
+ * be identifiers or components of the same concrete class.
+ */
+export function subsetMatch(reference, candidate) {
+    if (reference === candidate)
+        return true;
+    if (!(candidate instanceof reference.constructor))
+        return false;
+    const ctor = reference.constructor;
+    // Components (and any class without a declared attribute table) match
+    // conservatively: equal serialized forms. A component that wants the
+    // wildcard/strict rules declares a `static attributes` table.
+    if (!ctor.attributes || typeof ctor.attributes !== "object") {
+        const a = reference.toWire?.() ?? null;
+        const b = candidate?.toWire?.() ?? null;
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    const strict = new Set(ctor.subsetStrict ?? []);
+    const ignored = new Set([
+        ...(ctor.subsetIgnoredAttributes ?? []),
+        ...(reference.subsetAllPartsWildcard?.()
+            ? ALL_PARTS_ATTRIBUTES
+            : []),
+    ]);
+    return Object.keys(ctor.attributes).every((name) => {
+        if (ignored.has(name))
+            return true;
+        const mine = reference[name];
+        const theirs = candidate[name];
+        if (strict.has(name))
+            return exactMatch(mine, theirs);
+        return valueMatch(mine, theirs);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pubid/pubid",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "TypeScript PubID identifiers: resolution, normalization and canonical hashes for every identifier in the pubid-testsuite corpus (41 standards bodies), with a conformance runner mirroring the Ruby reference",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,8 @@
     "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
     "conformance": "tsc -p tsconfig.json && node dist/conformance/cli.js",
     "prepublishOnly": "tsc -p tsconfig.json",
-    "artifact": "tsc -p tsconfig.json && node scripts/build-artifact.mjs"
+    "artifact": "tsc -p tsconfig.json && node scripts/build-artifact.mjs",
+    "doc:api": "node scripts/api-reference.mjs"
   },
   "dependencies": {
     "parsanol": "^0.10.4",
@@ -22,6 +23,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
+    "typedoc": "^0.28.20",
     "typescript": "^5.6.0"
   },
   "files": [