@pubid/pubid 0.1.23 → 0.1.24

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);

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.24",
   "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": [