@pubid/pubid 0.1.5 → 0.1.7

package/dist/flavors/jcgm/index.js

@@ -288,6 +288,27 @@ class JcgmBuilder extends BaseBuilder {
 export function jcgmGrammarImplementation() {
     const builder = new JcgmBuilder();
     return {
+        // Inverse of JcgmUrnGenerator (lib/pubid/jcgm/urn_parser.rb): rebuild
+        // identifiers DIRECTLY from the URN segments — re-parsing through the
+        // grammar flattened segments and lost languages/supplements.
+        parseUrn(urn) {
+            const parts = urn.replace(/^urn:jcgm:/, "").split(":");
+            if (parts[0] === "meeting") {
+                const number = toMeetingNumber(parts[1]);
+                const date = urnDate(parts[2]);
+                return new (KIND_CLASSES.meeting)({ number, date });
+            }
+            const markerAt = parts.findIndex((seg) => seg === "corrigendum" || seg === "amendment");
+            if (markerAt === -1) {
+                return buildUrnDocument(parts);
+            }
+            const kind = (parts[markerAt] === "amendment" ? "amendment" : "corrigendum");
+            const base = buildUrnDocument(parts.slice(0, markerAt));
+            const tail = parts.slice(markerAt + 1);
+            const number = tail[0] === undefined || tail[0] === "" ? undefined : tail[0];
+            const date = urnDate(tail[1]);
+            return new (KIND_CLASSES[kind])({ base, number, date });
+        },
         parse(input) {
             const tree = parseGrammar(jcgmGrammar, input);
             if (typeof tree !== "object" || tree === null || Array.isArray(tree)) {
@@ -297,4 +318,44 @@ export function jcgmGrammarImplementation() {
         },
     };
 }
+// lib/pubid/jcgm/urn_parser.rb build_document: Guide vs GumGuide by the
+// "gum." number prefix; the year and language segments are matched by
+// pattern, not position.
+function buildUrnDocument(parts) {
+    const number = parts[0];
+    if (number === undefined || number === "") {
+        throw new Error("JCGM URN has no document number");
+    }
+    const gum = number.startsWith("gum.");
+    const rest = parts.slice(1);
+    const year = rest.find((seg) => /^(19|20)\d{2}$/.test(seg));
+    const langSegment = rest.find((seg) => /^[a-z]{2}(,[a-z]{2})*$/.test(seg));
+    const langLetters = {
+        ru: "R", fr: "F", en: "E", ar: "A", es: "S", de: "D",
+    };
+    const languages = langSegment
+        ? langSegment.split(",").map((code) => new Language({ code, originalCode: langLetters[code] ?? code }))
+        : [];
+    const cls = gum ? KIND_CLASSES["gum-guide"] : KIND_CLASSES.guide;
+    const cleanNumber = gum ? number.slice("gum.".length) : number;
+    return new cls({
+        number: cleanNumber,
+        date: year ? new PubidDate({ year }) : undefined,
+        languages,
+    });
+}
+// nil for an absent year; a component for a well-formed 19xx/20xx year;
+// anything else rejects (no re-parse validates it any more).
+function urnDate(segment) {
+    if (segment === undefined || segment === "")
+        return undefined;
+    if (!/^(19|20)\d{2}$/.test(segment)) {
+        throw new Error(`Invalid year in JCGM URN: ${JSON.stringify(segment)}`);
+    }
+    return new PubidDate({ year: segment });
+}
+// "011" reads back as "11" (Identifiers::Meeting.ordinal normalization).
+function toMeetingNumber(segment) {
+    return String(Number(segment));
+}
 export { isObj };

package/dist/flavors/nist/grammar.js

@@ -271,12 +271,19 @@ function buildRules() {
         .as("series")
         .then(space.or(dot))
         .as("circ_series")
-        .then(str("supp")
+        .then(
+    // Bare supplement marker to the whole series, no base number
+    // ("NBS.CIRC.sup" — testsuite#5 C4).
+    ((str("supp").or(str("sup"))).then(monthAbbrev().then(digits).as("supplement_month_year").or(digits.as("supp_number").then(slash, digits.as("supp_year")).as("supplement_slash_year"), str("").as("supplement_empty")).maybe())).or(
+    // Date-range supplement (no base document).
+    str("supp")
         .then(monthAbbrev().as("supp_month_start"), digits.as("supp_year_start"), dash, monthAbbrev().as("supp_month_end"), digits.as("supp_year_end"))
         .as("supplement_date_range")
         .or((str("supp").or(str("sup")))
         .then(match("[0-9]").repeat(4, 4).as("supp_year_start"), dash, match("[0-9]").repeat(4, 4).as("supp_year_end"))
-        .as("supplement_date_range"), (digits.as("base_number").then(str("e"), digits.as("edition_number")).or(digits
+        .as("supplement_date_range"))).or(
+    // Base identifier + supplement.
+    (digits.as("base_number").then(str("e"), digits.as("edition_number")).or(digits
         .as("base_number")
         .then(lowerLetter.as("revision_letter"), digits.as("revision_number")), digits.as("base_number").then(upperLetter.as("letter_suffix")), digits.as("simple_number")))
         .as("base_portion")

package/dist/flavors/nist/index.js

@@ -803,6 +803,7 @@ class NistBuilder {
             h["supplement_month_year"] !== undefined ||
             h["supplement_year"] !== undefined ||
             h["supplement"] !== undefined ||
+            h["supplement_empty"] !== undefined ||
             h["base_portion"] !== undefined) {
             return this.buildCircularSupplement(h);
         }
@@ -1094,9 +1095,12 @@ class NistBuilder {
             return this.buildCircularSupplementWrapper(h);
         }
         const seriesValue = isObj(h["circ_series"]) ? s(h["circ_series"]["series"]) : s(h["series"]);
+        // The dotted series literal ("NBS.CIRC") names its publisher in the
+        // first token; the builder default would render "NIST" instead.
+        const seriesPublisher = seriesValue?.startsWith("NBS") ? "NBS" : undefined;
         if (isObj(h["supplement_date_range"])) {
             const range = h["supplement_date_range"];
-            const identifier = this.build({ series: seriesValue }, "short");
+            const identifier = this.build({ series: seriesValue, publisher: seriesPublisher }, "short");
             const ms = s(range["supp_month_start"]);
             const ys = s(range["supp_year_start"]);
             const me = s(range["supp_month_end"]);
@@ -1109,7 +1113,7 @@ class NistBuilder {
             });
             return identifier;
         }
-        const base = this.buildCircularSupplementBase(h, seriesValue);
+        const base = this.buildCircularSupplementBase(h, seriesValue, seriesPublisher);
         const self = base;
         const raw = h["supplement_month_year"] !== undefined
             ? s(h["supplement_month_year"])
@@ -1119,11 +1123,11 @@ class NistBuilder {
         self["supplement"] = NistSupplement.fromRaw(raw);
         return base;
     }
-    buildCircularSupplementBase(h, seriesValue) {
+    buildCircularSupplementBase(h, seriesValue, seriesPublisher) {
         const basePortion = h["base_portion"];
         if (!isObj(basePortion)) {
             return this.build({
-                publisher: s(h["publisher"]),
+                publisher: s(h["publisher"]) ?? seriesPublisher,
                 series: seriesValue ?? s(h["series"]),
                 first_number: s(h["first_number"]),
             }, s(h["parsed_format"]) ?? "short");

package/dist/flavors/nist/model.js

@@ -516,11 +516,18 @@ export class NistIdentifier extends BaseIdentifier {
         else if (this.volume !== undefined && this.issue_number !== undefined) {
             result += `${this.volume.render()}n${this.issue_number.number}`;
         }
-        if (this.edition !== undefined)
-            result += this.edition.render();
+        // With a number the edition glues per the NIST spec ("800-53r5");
+        // series-only editions take a dot separator ("NBS.CIRC.e2" — the
+        // attested raw spelling; testsuite#5 C4/C5).
+        if (this.edition !== undefined) {
+            result += this.number !== undefined ? this.edition.render() : `.${this.edition.render()}`;
+        }
         if (this.version_component !== undefined)
             result += this.version_component.render();
-        result += this.supplementShort();
+        // A series-only supplement takes the dot itself ("NBS.CIRC.sup").
+        if (this.supplement !== undefined) {
+            result += this.number !== undefined ? this.supplementShort() : `.${this.supplementShort()}`;
+        }
         if (this.update_component !== undefined)
             result += this.update_component.render("mr");
         if (this.stage !== undefined) {

package/dist/flavors/oiml/implementation.js

@@ -14,6 +14,22 @@ function flavorOf(input) {
  */
 export function oimlGrammarImplementation() {
     return {
+        // Inverse of OimlUrnGenerator (lib/pubid/oiml/urn_parser.rb): strip the
+        // "urn:oiml:" namespace, rebuild the human head "OIML <TYPE> <locator>",
+        // and re-parse. Mirrors the reference exactly — the year and language
+        // URN segments are not carried back (the reference parser reads only
+        // the type and the number-part locator).
+        parseUrn(urn) {
+            const body = urn.replace(/^urn:oiml:/i, "");
+            const parts = body.split(":");
+            const typeToken = parts[0] ?? "";
+            const number = parts[1];
+            const displayType = typeToken.toLowerCase() === "bulletin" ? "Bulletin" : typeToken.toUpperCase();
+            let text = `OIML ${displayType}`;
+            if (number !== undefined && number !== "")
+                text += ` ${number}`;
+            return this.parse(text);
+        },
         parse(input) {
             // The co-published form carries both identifiers joined by "|":
             // "ISO 4064-1:2024|OIML R 49-1:2024". The first side is another

package/dist/pg/runtime.d.ts

@@ -0,0 +1,85 @@
+type PgArtifactJs = any;
+/** A field requirement from the binding-requirements schema. */
+export interface FieldRequirement {
+    type: string;
+    card: string;
+    preprocess?: string;
+}
+/** The binding-requirements schema record for one entry. */
+export interface EntrySchema {
+    root: string;
+    fields: Record<string, FieldRequirement>;
+    examples: {
+        input: string;
+        captures: Record<string, unknown>;
+    }[];
+}
+export type Schema = Record<string, EntrySchema>;
+/**
+ * A loaded, checksum-verified PG artifact with its schema.
+ * Construction throws when the checksum does not verify.
+ */
+export declare class PgRuntime {
+    readonly artifact: PgArtifactJs;
+    readonly schema: Schema;
+    readonly renderSpec: Record<string, RenderSegment[]>;
+    readonly entry: string;
+    readonly defaultEntry: string | null;
+    readonly envelope: Record<string, unknown>;
+    constructor(artifactJson: string, entry?: string);
+    /** Load an artifact JSON file and verify its checksum. */
+    static fromFile(path: string, entry?: string): PgRuntime;
+    /** The default artifacts directory (the pubid-grammar checkout). */
+    static artifactsDir(): string;
+    static load(grammar: string, entry?: string): PgRuntime;
+    /** Parse with the native wasm engine; returns the parsanol-shape tree. */
+    parseShape(input: string): unknown;
+    /** Apply the entry's bindings to a parsanol-shape tree. */
+    applyBindings(shape: unknown): Record<string, unknown>;
+    /** Parse and bind in one step. */
+    parseAndBind(input: string): Record<string, unknown> | null;
+    /**
+     * Schema-driven materialization: the schema (from the artifact, not
+     * hand-written model code) declares the fields a data model must
+     * implement; the bound captures populate a structurally-typed object.
+     * Card `1*`/`*` fields become arrays; `0..1` fields become nullable.
+     */
+    materialize(input: string): Materialized | null;
+    /** Render the identifier string from a bound map (F6). */
+    render(bound: Record<string, unknown>, variant?: string): string;
+    /** Parse, bind, and render in one step. */
+    renderString(input: string, variant?: string): string | null;
+    /** Evaluate a named derive spec against a bound map (F6). */
+    derive(name: string, bound: Record<string, unknown>): string;
+    /** Parse, bind, and evaluate a derive spec in one step. */
+    deriveString(input: string, name: string): string | null;
+    /** Run the artifact's embedded tests; empty list means green. */
+    runTests(): string[];
+}
+/** F6 v1 derive evaluator: {field} interpolates from the bound map. */
+export declare function deriveTemplate(derive: Record<string, string>, name: string, bound: Record<string, unknown>): string;
+export type RenderSegment = {
+    type: "field";
+    field: string;
+} | {
+    type: "literal";
+    text: string;
+} | {
+    type: "cond";
+    field: string;
+    then: RenderSegment[];
+};
+/** F6 v1 generic renderer: field / literal / cond-presence segments. */
+export declare function renderSegments(segments: RenderSegment[] | null, bound: Record<string, unknown>): string;
+/** A schema-materialized identifier: typed fields plus provenance. */
+export interface Materialized {
+    entry: string;
+    attributes: Record<string, unknown>;
+}
+/**
+ * Schema-driven materialization independent of any wasm handle —
+ * the same function the model layer will build on (T2 codegen emits the
+ * static view of exactly these fields).
+ */
+export declare function materializeFromSchema(schema: EntrySchema, bound: Record<string, unknown>): Materialized;
+export {};

package/dist/pg/runtime.js

@@ -0,0 +1,170 @@
+//! PG artifact runtime for TypeScript (TODO 12 / T1): checksum-verified
+//! artifact load, native wasm parse, bindings application, and
+//! schema-driven materialization. The engine is the vendored
+//! parsanol wasm package (PgArtifactJs, C9) — no grammar code lives in
+//! this repo; the artifact is the contract.
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/** Walk up from this module to the package root (which holds package.json). */
+function packageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (; !existsSync(join(dir, "package.json")); dir = dirname(dir)) {
+        if (dir === dirname(dir))
+            throw new Error("package.json not found above pg runtime");
+    }
+    return dir;
+}
+// The vendored wasm glue is CommonJS and lives outside the compiled tree,
+// so resolve it against the package root at runtime.
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const wasm = require(join(packageRoot(), "vendor", "parsanol-wasm", "parsanol.js"));
+/**
+ * A loaded, checksum-verified PG artifact with its schema.
+ * Construction throws when the checksum does not verify.
+ */
+export class PgRuntime {
+    artifact;
+    schema;
+    renderSpec;
+    entry;
+    defaultEntry;
+    envelope;
+    constructor(artifactJson, entry) {
+        this.envelope = JSON.parse(artifactJson);
+        this.artifact = new wasm.PgArtifactJs(artifactJson);
+        this.schema = JSON.parse(this.artifact.schema());
+        this.renderSpec =
+            this.envelope["render"] ?? {};
+        // The compiler bakes default_entry: JSON key order is not preserved
+        // across engines, so the sorted entry list cannot rederive it.
+        this.defaultEntry =
+            JSON.parse(artifactJson)["default_entry"] ?? null;
+        this.entry = entry ?? this.defaultEntry ?? this.artifact.entryNames()[0];
+    }
+    /** Load an artifact JSON file and verify its checksum. */
+    static fromFile(path, entry) {
+        return new PgRuntime(readFileSync(path, "utf8"), entry);
+    }
+    /** The default artifacts directory (the pubid-grammar checkout). */
+    static artifactsDir() {
+        const env = process.env.PG_ARTIFACT_DIR;
+        if (env)
+            return env;
+        // pubid-grammar is a sibling checkout in the pubid workspace.
+        return join(packageRoot(), "..", "pubid-grammar", "artifacts");
+    }
+    static load(grammar, entry) {
+        return PgRuntime.fromFile(join(PgRuntime.artifactsDir(), `${grammar}.json`), entry);
+    }
+    /** Parse with the native wasm engine; returns the parsanol-shape tree. */
+    parseShape(input) {
+        return JSON.parse(this.artifact.parseShape(this.entry, input));
+    }
+    /** Apply the entry's bindings to a parsanol-shape tree. */
+    applyBindings(shape) {
+        return JSON.parse(this.artifact.applyBindings(this.entry, JSON.stringify(shape)));
+    }
+    /** Parse and bind in one step. */
+    parseAndBind(input) {
+        try {
+            return JSON.parse(this.artifact.parseAndBind(this.entry, input));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Schema-driven materialization: the schema (from the artifact, not
+     * hand-written model code) declares the fields a data model must
+     * implement; the bound captures populate a structurally-typed object.
+     * Card `1*`/`*` fields become arrays; `0..1` fields become nullable.
+     */
+    materialize(input) {
+        const bound = this.parseAndBind(input);
+        if (bound === null)
+            return null;
+        const schema = this.schema[this.entry];
+        if (!schema)
+            throw new Error(`artifact has no schema for entry ${this.entry}`);
+        return materializeFromSchema(schema, bound);
+    }
+    /** Render the identifier string from a bound map (F6). */
+    render(bound, variant = "default") {
+        return renderSegments((this.renderSpec[variant] ?? null), bound);
+    }
+    /** Parse, bind, and render in one step. */
+    renderString(input, variant = "default") {
+        const bound = this.parseAndBind(input);
+        return bound === null ? null : this.render(bound, variant);
+    }
+    /** Evaluate a named derive spec against a bound map (F6). */
+    derive(name, bound) {
+        return deriveTemplate((this.envelope["derive"] ?? {}), name, bound);
+    }
+    /** Parse, bind, and evaluate a derive spec in one step. */
+    deriveString(input, name) {
+        const bound = this.parseAndBind(input);
+        return bound === null ? null : this.derive(name, bound);
+    }
+    /** Run the artifact's embedded tests; empty list means green. */
+    runTests() {
+        return JSON.parse(this.artifact.runTests());
+    }
+}
+/** F6 v1 derive evaluator: {field} interpolates from the bound map. */
+export function deriveTemplate(derive, name, bound) {
+    const template = derive[name];
+    if (template === undefined)
+        throw new Error(`derive spec ${name} not declared`);
+    return template.replace(/\{(\w+)\}/g, (_, field) => {
+        const value = bound[field];
+        return value === undefined || value === null ? "" : String(value);
+    });
+}
+/** F6 v1 generic renderer: field / literal / cond-presence segments. */
+export function renderSegments(segments, bound) {
+    let out = "";
+    for (const segment of segments ?? []) {
+        if (segment.type === "field") {
+            const value = bound[segment.field];
+            out += value === undefined || value === null ? "" : String(value);
+        }
+        else if (segment.type === "literal") {
+            out += segment.text;
+        }
+        else if (segment.type === "cond") {
+            const value = bound[segment.field];
+            if (value !== undefined && value !== null)
+                out += renderSegments(segment.then, bound);
+        }
+    }
+    return out;
+}
+/**
+ * Schema-driven materialization independent of any wasm handle —
+ * the same function the model layer will build on (T2 codegen emits the
+ * static view of exactly these fields).
+ */
+export function materializeFromSchema(schema, bound) {
+    const attributes = {};
+    for (const [path, requirements] of Object.entries(schema.fields)) {
+        const leaf = path.includes("[]")
+            ? (path.split("].").pop() ?? path)
+            : path;
+        const value = bound[leaf];
+        if (requirements.card.endsWith("*")) {
+            const list = Array.isArray(value) ? value : value === undefined ? [] : [value];
+            attributes[leaf] = list;
+        }
+        else if (requirements.card === "0..1") {
+            attributes[leaf] = value === undefined ? null : value;
+        }
+        else {
+            attributes[leaf] = value;
+        }
+    }
+    return { entry: schema.root, attributes };
+}

package/dist/pg/suite.d.ts

@@ -0,0 +1,20 @@
+import { PgRuntime } from "./runtime.js";
+export type TestKind = "accept" | "reject" | "example";
+export interface SuiteTest {
+    kind: TestKind;
+    input: string;
+    expect?: Record<string, string>;
+}
+export interface Suite {
+    name: string;
+    entry?: string;
+    tests: SuiteTest[];
+}
+/** Parse one *.pgtest file (same grammar as Parsanol::PG::Suite#read_file). */
+export declare function readSuite(text: string, name: string): Suite;
+/** Load every *.pgtest file in a directory. */
+export declare function loadSuites(dir: string): Suite[];
+/** Run a suite against a runtime; returns failure descriptions. */
+export declare function runSuite(runtime: PgRuntime, suite: Suite): string[];
+/** The default suites directory (the pubid-grammar checkout). */
+export declare function suitesDir(): string;

package/dist/pg/suite.js

@@ -0,0 +1,90 @@
+//! T3: external *.pgtest suites run through the wasm runtime. The suite
+//! syntax matches the Ruby loader (Parsanol::PG::Suite): a
+//! `suite <name> [for <entry>] { ... }` header with accept / reject /
+//! example lines. Green means Ruby and TypeScript agree on the contract.
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { PgRuntime } from "./runtime.js";
+const LINE = /^\s*(accept|reject|example)\s+"((?:[^"\\]|\\.)*)"(?:\s*\{([^}]*)\})?\s*$/;
+const HEADER = /suite\s+(\w+)(?:\s+for\s+entry\s+(\w+))?\s*\{/;
+/** Parse one *.pgtest file (same grammar as Parsanol::PG::Suite#read_file). */
+export function readSuite(text, name) {
+    const body = text.replace(/^#[^\n]*\n/gm, "");
+    const header = HEADER.exec(body);
+    if (!header) {
+        throw new Error(`${name}: expected 'suite <name> [for <entry>] { ... }'`);
+    }
+    const tests = [];
+    for (const line of body.slice((header.index ?? 0) + header[0].length).split("\n")) {
+        if (line.trim() === "}")
+            break;
+        const match = LINE.exec(line);
+        if (!match)
+            continue;
+        const kind = match[1];
+        const rawInput = match[2] ?? "";
+        const input = JSON.parse(`"${rawInput}"`);
+        const expect = {};
+        if (match[3]) {
+            for (const pair of match[3].split(",")) {
+                const kv = /(\w+)\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(pair);
+                const key = kv?.[1];
+                const raw = kv?.[2];
+                if (key && raw !== undefined)
+                    expect[key] = JSON.parse(`"${raw}"`);
+            }
+        }
+        tests.push(kind === "example" ? { kind, input, expect } : { kind, input });
+    }
+    const entry = header[2];
+    return entry === undefined
+        ? { name: header[1] ?? "suite", tests }
+        : { name: header[1] ?? "suite", entry, tests };
+}
+/** Load every *.pgtest file in a directory. */
+export function loadSuites(dir) {
+    return readdirSync(dir)
+        .filter((file) => file.endsWith(".pgtest"))
+        .map((file) => readSuite(readFileSync(join(dir, file), "utf8"), file.replace(/\.pgtest$/, "")));
+}
+/** Run a suite against a runtime; returns failure descriptions. */
+export function runSuite(runtime, suite) {
+    const failures = [];
+    const entry = suite.entry ?? runtime.entry;
+    for (const test of suite.tests) {
+        // The wasm runtime throws on parse failure; that is the reject signal.
+        let bound = null;
+        try {
+            bound = runtime.artifact.parseAndBind(entry, test.input);
+        }
+        catch {
+            bound = null;
+        }
+        if (test.kind === "reject") {
+            if (bound !== null) {
+                failures.push(`test ${JSON.stringify(test.input)}: expected the input to be rejected`);
+            }
+            continue;
+        }
+        if (bound === null) {
+            failures.push(`test ${JSON.stringify(test.input)}: expected the input to parse`);
+            continue;
+        }
+        if (test.kind === "example") {
+            const parsed = JSON.parse(bound);
+            for (const [key, value] of Object.entries(test.expect ?? {})) {
+                if (parsed[key] !== value) {
+                    failures.push(`test ${JSON.stringify(test.input)}: expected captures ${key}: ${JSON.stringify(value)}, got ${JSON.stringify(parsed[key])}`);
+                }
+            }
+        }
+    }
+    return failures;
+}
+/** The default suites directory (the pubid-grammar checkout). */
+export function suitesDir() {
+    const env = process.env.PG_SUITES_DIR;
+    if (env)
+        return env;
+    return join(PgRuntime.artifactsDir(), "..", "suites");
+}

package/dist/urn/parsers.d.ts

@@ -0,0 +1,5 @@
+import type { Identifier } from "../conformance/implementation.js";
+import { type UrnParserDef } from "./types.js";
+export declare const URN_PARSERS: Record<string, UrnParserDef>;
+export declare function lookupUrnParser(flavor: string): UrnParserDef | undefined;
+export declare function parseUrnFor(def: UrnParserDef, urn: string, parse: (text: string) => Identifier): Identifier;