@pubid/pubid 0.1.3 → 0.1.4

package/dist/flavors/xsf/index.js

@@ -0,0 +1,65 @@
+import { match, str } from "../../grammar/engine.js";
+import { ParseFailed, parseGrammar } from "../../grammar/engine.js";
+import { BaseIdentifier, registerType } from "../../model/identifier.js";
+import { extendAttributes, keyValue } from "../../model/attribute.js";
+import { BaseUrnGenerator } from "../../model/urn-generator.js";
+import { BaseBuilder } from "../../model/builder.js";
+/**
+ * 1:1 port of lib/pubid/xsf/ on the unified model. XEP numbers, plus the
+ * two named documents ("XEP README", "XEP xxxx") kept verbatim. URN:
+ * urn:xsf:xep:<number> (the Ruby flavor's own generator).
+ */
+// The editor README and the xep-xxxx template reach pubid as real
+// primary docids.
+const SPECIAL_NUMBERS = ["README", "xxxx"];
+function buildRules() {
+    const rules = {};
+    const rule = (name, build) => {
+        rules[name] = build();
+    };
+    const specialNumber = SPECIAL_NUMBERS.map((name) => str(name)).reduce((a, b) => a.or(b));
+    rule("special_number", () => specialNumber);
+    const digits = match("[0-9]").repeat(1, Infinity);
+    rule("digits", () => digits);
+    rule("identifier", () => str("XEP").then(str(" "), digits.or(specialNumber).as("number")));
+    rule("root", () => rules["identifier"]);
+    return rules;
+}
+export const xsfGrammar = {
+    rules: buildRules(),
+    root: "root",
+};
+class XsfUrnGenerator extends BaseUrnGenerator {
+    generate() {
+        return ["urn", "xsf", "xep", this.identifier.number].join(":");
+    }
+}
+export class XsfIdentifier extends BaseIdentifier {
+    static polymorphicName = "pubid:xsf:xep";
+    static attributes = extendAttributes(BaseIdentifier, {
+        number: { type: "string" },
+    });
+    static mappings = keyValue({ wire: "number", to: "number" });
+    static urnGenerator = XsfUrnGenerator;
+    render() {
+        return `XEP ${this.number}`;
+    }
+}
+registerType(XsfIdentifier);
+class XsfBuilder extends BaseBuilder {
+    defaultIdentifierClass() {
+        return XsfIdentifier;
+    }
+}
+export function xsfGrammarImplementation() {
+    const builder = new XsfBuilder();
+    return {
+        parse(input) {
+            const tree = parseGrammar(xsfGrammar, input);
+            if (typeof tree !== "object" || tree === null || Array.isArray(tree)) {
+                throw new ParseFailed("XSF: unexpected parse tree", 0);
+            }
+            return builder.build(tree);
+        },
+    };
+}

package/dist/grammar/engine.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A parslet-compatible parser-combinator engine.
+ *
+ * The Ruby pubid grammars are declarative parslet rule trees; porting a
+ * flavor 1:1 requires the TypeScript engine to reproduce parslet's tree
+ * semantics exactly, because the Ruby builders read those trees. The
+ * semantics below were pinned empirically against parslet 2.0 (see the
+ * porting guide in docs/PORTING.md):
+ *
+ * - atoms produce a string, a capture hash, an array, or nil
+ * - sequences fold with `combine`: string+string concat; a plain string
+ *   is DISCARDED when combined with a capture; hash+hash merges and a
+ *   duplicate key raises; nil is transparent
+ * - `.as(key)` wraps the result: {key: result}
+ * - `.repeat` is greedy and does NOT backtrack a successful iteration to
+ *   satisfy an outer minimum (parslet: "Expected at least N of ...");
+ *   results are an array when any iteration captured, else a concat string
+ * - `.maybe` is special-cased like parslet's Maybe: one attempt, nil on
+ *   failure (not an empty array)
+ * - `absent?`/`present?` are zero-width lookaheads
+ * - full input consumption is enforced the way parslet 2.0 does it: a
+ *   `consumeAll` flag is threaded down the parse spine — the root starts
+ *   with it, a Sequence hands it ONLY to its last child, Alternatives
+ *   pass it to every branch, and Repetition iterations never get it. An
+ *   atom that succeeds while unconsumed input remains FAILS (parslet
+ *   Base#apply's "Don't know what to do with ..." check). Because that
+ *   failure is an ordinary match failure, an enclosing Alternative
+ *   retries its next branch — so `a | b` DOES re-try `b` when `a`
+ *   matched but left trailing input (pinned against parslet: bare
+ *   "080442957X" reaches ISBN's second body alternative this way).
+ */
+export declare class ParseFailed extends Error {
+    readonly pos: number;
+    constructor(message: string, pos: number);
+}
+export type Tree = string | number | TreeObject | Tree[] | null | undefined;
+export interface TreeObject {
+    [key: string]: Tree;
+}
+/** Context threaded through every match attempt. */
+declare class Ctx {
+    input: string;
+    pos: number;
+    constructor(input: string);
+}
+export interface Atom {
+    /** Attempt a match at ctx.pos; failure throws Fail. */
+    _match(ctx: Ctx, consumeAll: boolean): Tree | undefined;
+}
+/** Builder-side sugar: chainable wrapper. */
+export declare class P {
+    readonly atom: Atom;
+    constructor(atom: Atom);
+    then(...next: (P | Atom)[]): P;
+    or(...others: (P | Atom)[]): P;
+    repeat(min?: number, max?: number): P;
+    maybe(): P;
+    as(key: string): P;
+    absent(): P;
+    present(): P;
+}
+export declare function unwrap(p: P | Atom): Atom;
+export declare function str(s: string): P;
+/** parslet's match: a single-character regex match, e.g. match("[a-z]"). */
+export declare function match(pattern: string): P;
+/** A named rule reference (lazily resolved — grammars are recursive). */
+export declare function ref(rules: Record<string, P | Atom>, name: string): P;
+export interface Grammar {
+    rules: Record<string, P | Atom>;
+    root: string;
+}
+/**
+ * Parse the whole input with the grammar's root rule, parslet-style:
+ * full consumption is enforced by the root's consumeAll flag, so an
+ * Alternative at the spine retries a branch that left trailing input.
+ */
+export declare function parseGrammar(grammar: Grammar, input: string): Tree;
+export {};

package/dist/grammar/engine.js

@@ -0,0 +1,351 @@
+/**
+ * A parslet-compatible parser-combinator engine.
+ *
+ * The Ruby pubid grammars are declarative parslet rule trees; porting a
+ * flavor 1:1 requires the TypeScript engine to reproduce parslet's tree
+ * semantics exactly, because the Ruby builders read those trees. The
+ * semantics below were pinned empirically against parslet 2.0 (see the
+ * porting guide in docs/PORTING.md):
+ *
+ * - atoms produce a string, a capture hash, an array, or nil
+ * - sequences fold with `combine`: string+string concat; a plain string
+ *   is DISCARDED when combined with a capture; hash+hash merges and a
+ *   duplicate key raises; nil is transparent
+ * - `.as(key)` wraps the result: {key: result}
+ * - `.repeat` is greedy and does NOT backtrack a successful iteration to
+ *   satisfy an outer minimum (parslet: "Expected at least N of ...");
+ *   results are an array when any iteration captured, else a concat string
+ * - `.maybe` is special-cased like parslet's Maybe: one attempt, nil on
+ *   failure (not an empty array)
+ * - `absent?`/`present?` are zero-width lookaheads
+ * - full input consumption is enforced the way parslet 2.0 does it: a
+ *   `consumeAll` flag is threaded down the parse spine — the root starts
+ *   with it, a Sequence hands it ONLY to its last child, Alternatives
+ *   pass it to every branch, and Repetition iterations never get it. An
+ *   atom that succeeds while unconsumed input remains FAILS (parslet
+ *   Base#apply's "Don't know what to do with ..." check). Because that
+ *   failure is an ordinary match failure, an enclosing Alternative
+ *   retries its next branch — so `a | b` DOES re-try `b` when `a`
+ *   matched but left trailing input (pinned against parslet: bare
+ *   "080442957X" reaches ISBN's second body alternative this way).
+ */
+export class ParseFailed extends Error {
+    pos;
+    constructor(message, pos) {
+        super(`${message} at line 1 char ${pos + 1}`);
+        this.name = "ParseFailed";
+        this.pos = pos;
+    }
+}
+/** Context threaded through every match attempt. */
+class Ctx {
+    input;
+    pos = 0;
+    constructor(input) {
+        this.input = input;
+    }
+}
+class Fail extends Error {
+}
+function attempt(ctx, fn) {
+    const saved = ctx.pos;
+    try {
+        return fn();
+    }
+    catch (e) {
+        if (e instanceof Fail) {
+            ctx.pos = saved;
+            return undefined;
+        }
+        throw e;
+    }
+}
+/**
+ * parslet's Base#apply: run the atom's try, then — when the caller
+ * demanded full consumption and input is left over — rewind and fail.
+ * This is what lets an enclosing Alternative retry after a branch that
+ * matched but did not consume everything.
+ */
+function applyAtom(atom, ctx, consumeAll) {
+    const saved = ctx.pos;
+    const result = atom._match(ctx, consumeAll);
+    if (consumeAll && ctx.pos < ctx.input.length) {
+        ctx.pos = saved;
+        throw new Fail(`Don't know what to do with ${JSON.stringify(ctx.input.slice(ctx.pos, ctx.pos + 10))}`);
+    }
+    return result;
+}
+/** Combine two sequence results the way parslet's Sequence does. */
+function combine(a, b) {
+    if (a === undefined || a === null)
+        return b;
+    if (b === undefined || b === null)
+        return a;
+    if (typeof a === "string" && typeof b === "string")
+        return a + b;
+    // A plain string is discarded when the other side carries structure.
+    if (typeof a === "string" && typeof b === "object")
+        return b;
+    if (typeof b === "string" && typeof a === "object")
+        return a;
+    if (typeof a === "object" && typeof b === "object") {
+        if (!Array.isArray(a) && !Array.isArray(b)) {
+            // parslet merge on duplicate keys: warn and keep the LATTER value
+            // (astm's dual unit relies on this — the second :letter wins).
+            const out = { ...a };
+            for (const [k, v] of Object.entries(b)) {
+                if (k in out) {
+                    console.warn(`Duplicate subtrees while merging result of sequence (keys: :${k}); only the values of the latter will be kept.`);
+                }
+                out[k] = v;
+            }
+            return out;
+        }
+        return [...flatten(a), ...flatten(b)];
+    }
+    // number + anything: stringify
+    return typeof b === "object" ? b : `${a}${b}`;
+}
+function flatten(t) {
+    return Array.isArray(t) ? t : [t];
+}
+class Str {
+    s;
+    constructor(s) {
+        this.s = s;
+    }
+    _match(ctx, _consumeAll) {
+        if (ctx.input.startsWith(this.s, ctx.pos)) {
+            ctx.pos += this.s.length;
+            return this.s;
+        }
+        throw new Fail(`Expected ${JSON.stringify(this.s)}`);
+    }
+}
+class Regex {
+    re;
+    constructor(pattern) {
+        // parslet anchors the pattern and consumes exactly ONE match
+        this.re = new RegExp(`^(?:${pattern})`);
+    }
+    _match(ctx, _consumeAll) {
+        const m = this.re.exec(ctx.input.slice(ctx.pos));
+        if (!m)
+            throw new Fail(`Expected match on ${this.re.source}`);
+        const matched = m[0];
+        ctx.pos += matched.length;
+        return matched;
+    }
+}
+class Seq {
+    parts;
+    constructor(parts) {
+        this.parts = parts;
+    }
+    _match(ctx, consumeAll) {
+        let acc = undefined;
+        for (let i = 0; i < this.parts.length; i++) {
+            // parslet Sequence: only the LAST child inherits the must-consume
+            // obligation.
+            const r = applyAtom(this.parts[i], ctx, consumeAll && i === this.parts.length - 1);
+            acc = acc === undefined && r === undefined ? undefined : combine(acc, r);
+        }
+        return acc;
+    }
+}
+class Alt {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    _match(ctx, consumeAll) {
+        let lastFail = "no alternative matched";
+        for (const option of this.options) {
+            const r = attempt(ctx, () => applyAtom(option, ctx, consumeAll));
+            if (r !== undefined)
+                return r;
+            lastFail = "alternative failed";
+        }
+        throw new Fail(lastFail);
+    }
+}
+class Repeat {
+    atom;
+    min;
+    max;
+    constructor(atom, min, max) {
+        this.atom = atom;
+        this.min = min;
+        this.max = max;
+    }
+    get inner() {
+        return this.atom instanceof P ? this.atom.atom : this.atom;
+    }
+    _match(ctx, consumeAll) {
+        const results = [];
+        let count = 0;
+        while (count < this.max) {
+            // parslet Repetition: iterations never carry the consume-all flag.
+            const r = attempt(ctx, () => applyAtom(this.inner, ctx, false));
+            if (r === undefined)
+                break;
+            results.push(r);
+            count++;
+            if (ctx.pos >= ctx.input.length && count < this.min)
+                break;
+        }
+        if (count < this.min) {
+            throw new Fail(`Expected at least ${this.min} of repetition`);
+        }
+        // A repetition that stopped on its own inner failure while input
+        // remains and full consumption was demanded fails here (parslet's
+        // post-loop unconsumed check); a repetition that hit its max leaves
+        // that to applyAtom.
+        if (consumeAll && count < this.max && ctx.pos < ctx.input.length) {
+            throw new Fail("Don't know what to do with trailing input after repetition");
+        }
+        if (results.some((r) => typeof r === "object"))
+            return results;
+        return results.join("");
+    }
+}
+class Maybe {
+    atom;
+    constructor(atom) {
+        this.atom = atom;
+    }
+    _match(ctx, consumeAll) {
+        const inner = this.atom instanceof P ? this.atom.atom : this.atom;
+        const r = attempt(ctx, () => applyAtom(inner, ctx, consumeAll));
+        if (r === undefined || r === "")
+            return undefined;
+        return r;
+    }
+}
+class As {
+    atom;
+    key;
+    constructor(atom, key) {
+        this.atom = atom;
+        this.key = key;
+    }
+    get inner() {
+        return this.atom instanceof P ? this.atom.atom : this.atom;
+    }
+    _match(ctx, consumeAll) {
+        const r = this.inner._match(ctx, consumeAll);
+        return { [this.key]: r === undefined ? null : r };
+    }
+}
+class Absent {
+    atom;
+    constructor(atom) {
+        this.atom = atom;
+    }
+    _match(ctx, _consumeAll) {
+        const inner = this.atom instanceof P ? this.atom.atom : this.atom;
+        const r = attempt(ctx, () => inner._match(ctx, false));
+        if (r !== undefined)
+            throw new Fail("unexpectedly matched");
+        return "";
+    }
+}
+class Present {
+    atom;
+    constructor(atom) {
+        this.atom = atom;
+    }
+    _match(ctx, _consumeAll) {
+        const inner = this.atom instanceof P ? this.atom.atom : this.atom;
+        // A true lookahead that NEVER consumes input, and fails exactly when
+        // the probe fails (parslet's present?): the position is restored in
+        // both cases, but a non-match re-raises the ordinary failure so an
+        // enclosing Alternative retries its next branch.
+        const saved = ctx.pos;
+        try {
+            inner._match(ctx, false);
+        }
+        catch (e) {
+            if (!(e instanceof Fail))
+                throw e;
+            ctx.pos = saved;
+            throw new Fail("present? probe did not match");
+        }
+        ctx.pos = saved;
+        return "";
+    }
+}
+class Ref {
+    rules;
+    name;
+    resolved;
+    constructor(rules, name) {
+        this.rules = rules;
+        this.name = name;
+    }
+    _match(ctx, consumeAll) {
+        if (!this.resolved) {
+            const rule = this.rules[this.name];
+            if (!rule)
+                throw new Error(`unknown rule :${this.name}`);
+            this.resolved = rule instanceof P ? rule.atom : rule;
+        }
+        return this.resolved._match(ctx, consumeAll);
+    }
+}
+/** Builder-side sugar: chainable wrapper. */
+export class P {
+    atom;
+    constructor(atom) {
+        this.atom = atom;
+    }
+    then(...next) {
+        return new P(new Seq([this.atom, ...next.map(unwrap)]));
+    }
+    or(...others) {
+        return new P(new Alt([this.atom, ...others.map(unwrap)]));
+    }
+    repeat(min = 0, max = Infinity) {
+        return new P(new Repeat(this.atom, min, max));
+    }
+    maybe() {
+        return new P(new Maybe(this.atom));
+    }
+    as(key) {
+        return new P(new As(this.atom, key));
+    }
+    absent() {
+        return new P(new Absent(this.atom));
+    }
+    present() {
+        return new P(new Present(this.atom));
+    }
+}
+export function unwrap(p) {
+    return p instanceof P ? p.atom : p;
+}
+export function str(s) {
+    return new P(new Str(s));
+}
+/** parslet's match: a single-character regex match, e.g. match("[a-z]"). */
+export function match(pattern) {
+    return new P(new Regex(pattern));
+}
+/** A named rule reference (lazily resolved — grammars are recursive). */
+export function ref(rules, name) {
+    return new P(new Ref(rules, name));
+}
+/**
+ * Parse the whole input with the grammar's root rule, parslet-style:
+ * full consumption is enforced by the root's consumeAll flag, so an
+ * Alternative at the spine retries a branch that left trailing input.
+ */
+export function parseGrammar(grammar, input) {
+    const ctx = new Ctx(input);
+    const root = new Ref(grammar.rules, grammar.root);
+    const result = attempt(ctx, () => applyAtom(root, ctx, true));
+    if (result === undefined) {
+        throw new ParseFailed(`Expected one of [${grammar.root.toUpperCase()}]`, ctx.pos);
+    }
+    return result;
+}

package/dist/model/attribute.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Declarative attributes and wire mappings — the TS mirror of pubid's
+ * `attribute` DSL + lutaml key_value mappings. Semantics pinned in
+ * TODO.unified/01-study-pubid-core.md §1-3.
+ *
+ * A flavor DECLARES its shape; BaseIdentifier derives serialization.
+ * The only imperative wire code allowed is a converter pair
+ * (`toWire`/`fromWire`), mirroring Ruby's `map "x", with: {to:, from:}`.
+ */
+import type { Component } from "./component.js";
+export type ScalarType = "string" | "integer" | "boolean";
+export type ComponentCtor = new (attrs: Record<string, unknown>) => Component;
+export type AttributeType = ScalarType | ComponentCtor | (new (...args: never[]) => unknown);
+export interface AttributeSpec {
+    type: AttributeType;
+    /** Value or thunk; a value equal to the default is dropped from the canonical hash. */
+    default?: unknown;
+    collection?: boolean;
+    /** Materialize [] when the input hash omits the key (tgpp parts). */
+    initializeEmpty?: boolean;
+}
+export type AttributeTable = Record<string, AttributeSpec>;
+/**
+ * Ruby snapshots the parent attribute table into each subclass at
+ * class-definition time; TS composes the same way — a subclass's table
+ * is the parent's plus its overrides.
+ */
+export declare function extendAttributes(parent: {
+    attributes: AttributeTable;
+}, defs: AttributeTable): AttributeTable;
+/**
+ * The base table mirrors Pubid::Identifier (identifier.rb:503-525),
+ * minus the slots no ported flavor populates yet (type, stage, locality,
+ * typed_stage — they join when a flavor needs them).
+ */
+export declare const BASE_ATTRIBUTES: AttributeTable;
+export interface FieldMapping {
+    /** Wire key. */
+    wire: string;
+    /** Attribute name. */
+    to: string;
+    /** Custom wire converter (Ruby `map ... with: {to:}`). */
+    toWire?: (model: Record<string, unknown>) => unknown;
+    /** Custom reader (Ruby `map ... with: {from:}`). */
+    fromWire?: (hash: Record<string, unknown>) => unknown;
+}
+export declare function keyValue(...fields: FieldMapping[]): FieldMapping[];
+/**
+ * The flat-scalar tables (identifier.rb:24-36): attribute name → the wire
+ * key its degenerate scalar is emitted under (note `date` RENAMES to
+ * `year`), and the single field each component degenerates to.
+ */
+export declare const FLAT_SCALAR_COMPONENTS: Record<string, string>;
+export declare const FLAT_SCALAR_FIELDS: Record<string, string>;

package/dist/model/attribute.js

@@ -0,0 +1,53 @@
+/**
+ * Declarative attributes and wire mappings — the TS mirror of pubid's
+ * `attribute` DSL + lutaml key_value mappings. Semantics pinned in
+ * TODO.unified/01-study-pubid-core.md §1-3.
+ *
+ * A flavor DECLARES its shape; BaseIdentifier derives serialization.
+ * The only imperative wire code allowed is a converter pair
+ * (`toWire`/`fromWire`), mirroring Ruby's `map "x", with: {to:, from:}`.
+ */
+import { PubidDate, Publisher, Language, Edition, Iteration } from "./component.js";
+/**
+ * Ruby snapshots the parent attribute table into each subclass at
+ * class-definition time; TS composes the same way — a subclass's table
+ * is the parent's plus its overrides.
+ */
+export function extendAttributes(parent, defs) {
+    return { ...parent.attributes, ...defs };
+}
+/**
+ * The base table mirrors Pubid::Identifier (identifier.rb:503-525),
+ * minus the slots no ported flavor populates yet (type, stage, locality,
+ * typed_stage — they join when a flavor needs them).
+ */
+export const BASE_ATTRIBUTES = {
+    number: { type: "string" },
+    part: { type: "string" },
+    subpart: { type: "string" },
+    stage_iteration: { type: Iteration },
+    date: { type: PubidDate },
+    edition: { type: Edition },
+    languages: { type: Language, collection: true },
+    publisher: { type: Publisher },
+    copublishers: { type: Publisher, collection: true },
+    all_parts: { type: "boolean", default: false },
+};
+export function keyValue(...fields) {
+    return fields;
+}
+/**
+ * The flat-scalar tables (identifier.rb:24-36): attribute name → the wire
+ * key its degenerate scalar is emitted under (note `date` RENAMES to
+ * `year`), and the single field each component degenerates to.
+ */
+export const FLAT_SCALAR_COMPONENTS = {
+    edition: "edition",
+    date: "year",
+    stage_iteration: "stage_iteration",
+};
+export const FLAT_SCALAR_FIELDS = {
+    edition: "number",
+    date: "year",
+    stage_iteration: "string",
+};

package/dist/model/builder.d.ts

@@ -0,0 +1,39 @@
+/**
+ * BaseBuilder — the TS mirror of Pubid::Builder::Base
+ * (TODO.unified/01 §5). The shared build loop: flatten the parslet tree
+ * (array of hashes → merged hash), ask selectClass for the concrete
+ * class, then assign each tree key through cast(); unknown keys are
+ * silently skipped; cast may return a hash to fan out.
+ */
+import type { BaseIdentifier } from "./identifier.js";
+import type { IdentifierStatic } from "./identifier.js";
+import { PubidDate } from "./component.js";
+import { Language } from "./component.js";
+type TreeValue = unknown;
+export declare abstract class BaseBuilder {
+    protected abstract defaultIdentifierClass(): IdentifierStatic;
+    /** Override to dispatch by data shape (type token, supplement marker…). */
+    protected selectClass(_data: Record<string, TreeValue>): IdentifierStatic;
+    /**
+     * Override to convert raw parsed values to components. Return a hash to
+     * assign multiple attributes, a single value, or null/undefined to skip.
+     */
+    protected cast(_key: string, value: TreeValue): TreeValue;
+    /** Override for non-attribute side effects; return true when consumed. */
+    protected handleKey(_identifier: BaseIdentifier, _key: string, _value: TreeValue): boolean;
+    build(data: Record<string, TreeValue> | Record<string, TreeValue>[]): BaseIdentifier;
+    private flattenArray;
+    private assignAttributes;
+    protected parseDate(value: unknown): PubidDate;
+    protected parseLanguages(value: unknown): Language[];
+    private static readonly ROMAN;
+    protected convertRomanToInteger(roman: unknown): string;
+    /**
+     * "1234-1-2" → {number, part?, subpart?}; roman parts convert to
+     * integers; normalizeNumberWithPart / extractLegacyYear are hooks.
+     */
+    protected parseNumberWithPart(value: unknown): Record<string, string | undefined>;
+    protected normalizeNumberWithPart(value: string): string;
+    protected extractLegacyYear(_number: string | undefined, _part: string | undefined): Record<string, string | undefined> | undefined;
+}
+export {};