@entelekheia/ref-id 0.1.0

package/dist/parse.js

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Decomposes a `ref:` identifier string against the loaded spec. Order of validation and
+// delegation to owning validators is the behaviour ADR-0001 keeps in code; every table, pattern
+// and key it consults comes from the spec object, never restated here.
+//
+// Order, and the precedence it produces: grammar → version → state and fragment decomposition,
+// including the repeated-key policy → (unsupported version stops here, decomposed and unvalidated)
+// → the two sides must not trade keys → qualifier values against their forms → refinement values
+// against their patterns and range constraints → dispatch: unknown type is `uncovered`, else the
+// locator goes to its validator. So a validator failure (`malformed` with the part) outranks
+// `uncovered`, which outranks `ok`.
+import { decodeReserved, tableFor } from "./encoding.js";
+import { fragmentPairGrammar, pattern, schemePrefix, statePairGrammar, topLevelGrammar } from "./grammar.js";
+import { loadSpec, part, status } from "./spec.js";
+import { assertImplemented, delegatedString, rangeHolds, validateLocator } from "./validators.js";
+function malformed(spec, input, failedPart, base) {
+    const result = {
+        input,
+        status: status(spec, "malformed"),
+        version: base.version ?? spec.version.default,
+        explicitVersion: base.explicitVersion ?? false,
+        type: base.type ?? "",
+        locator: base.locator ?? "",
+        qualifiers: base.qualifiers ?? [],
+        fragment: base.fragment ?? null,
+        part: part(spec, failedPart),
+    };
+    if (base.versionText !== undefined) {
+        result.versionText = base.versionText;
+    }
+    return result;
+}
+/** Splits `key=value` segments with the given pair grammar; a repeated key is malformed at that key. */
+function decomposePairs(spec, grammar, segments, failedPart) {
+    const pairs = [];
+    const seen = new Set();
+    for (const segment of segments) {
+        const match = grammar.exec(segment);
+        if (!match?.groups) {
+            return { ok: false, part: failedPart };
+        }
+        const key = match.groups.key ?? "";
+        if (seen.has(key)) {
+            return { ok: false, part: key };
+        }
+        seen.add(key);
+        pairs.push([key, match.groups.value ?? ""]);
+    }
+    return { ok: true, value: pairs };
+}
+function decomposeState(spec, raw) {
+    return decomposePairs(spec, statePairGrammar(spec), raw.split(spec.grammar.state.separator), "state");
+}
+function decomposeFragment(spec, raw) {
+    const segments = raw.split(spec.grammar.fragment.separator);
+    const path = segments[0] ?? "";
+    if (path === "") {
+        return { ok: false, part: "fragment" };
+    }
+    const refinements = decomposePairs(spec, fragmentPairGrammar(spec), segments.slice(1), "fragment");
+    if (!refinements.ok) {
+        return refinements;
+    }
+    return { ok: true, value: { path, refinements: refinements.value } };
+}
+/** True when every `%` in the value begins one of the table's percent-forms — the strict nested encoding. */
+function strictlyEncoded(value, table) {
+    const forms = Object.values(table);
+    let at = value.indexOf("%");
+    while (at !== -1) {
+        if (!forms.some((form) => value.startsWith(form, at))) {
+            return false;
+        }
+        at = value.indexOf("%", at + 1);
+    }
+    return true;
+}
+/** A qualifier value that nests an identifier: strictly encoded, decoded with the form's table, parsed one level down. */
+function tryNested(spec, form, value, depth) {
+    const maxDepth = form.depth ?? 0;
+    if (depth >= maxDepth || !value.startsWith(schemePrefix(spec))) {
+        return undefined;
+    }
+    const table = tableFor(spec, form);
+    if (!strictlyEncoded(value, table)) {
+        return undefined;
+    }
+    const decoded = decodeReserved(value, table);
+    const inner = parseInternal(spec, decoded, depth + 1);
+    // A nested identifier stays readable whatever its type or version; only a malformed one is refused.
+    return inner.status === status(spec, "malformed") ? undefined : decoded;
+}
+function matchForms(spec, formNames, value, depth) {
+    for (const formName of formNames) {
+        const form = spec.forms[formName];
+        if (!form) {
+            continue;
+        }
+        if (form.nested) {
+            const nested = tryNested(spec, form, value, depth);
+            if (nested !== undefined) {
+                return { matches: true, nested };
+            }
+            continue;
+        }
+        if (form.pattern && pattern(spec, form.pattern).test(value)) {
+            return { matches: true };
+        }
+    }
+    return { matches: false };
+}
+function parseInternal(spec, input, depth) {
+    const match = topLevelGrammar(spec).exec(input);
+    if (!match?.groups) {
+        return malformed(spec, input, "grammar", {});
+    }
+    const { version: versionText, type = "", locator = "", state, fragment: fragmentRaw } = match.groups;
+    const explicitVersion = versionText !== undefined;
+    const version = explicitVersion ? Number(versionText) : spec.version.default;
+    const head = { version, explicitVersion, type, locator };
+    if (explicitVersion) {
+        head.versionText = versionText;
+    }
+    let qualifiers = [];
+    if (state !== undefined) {
+        const decomposed = decomposeState(spec, state);
+        if (!decomposed.ok) {
+            return malformed(spec, input, decomposed.part, head);
+        }
+        qualifiers = decomposed.value;
+    }
+    head.qualifiers = qualifiers;
+    let fragment = null;
+    if (fragmentRaw !== undefined) {
+        const decomposed = decomposeFragment(spec, fragmentRaw);
+        if (!decomposed.ok) {
+            return malformed(spec, input, decomposed.part, head);
+        }
+        fragment = decomposed.value;
+    }
+    head.fragment = fragment;
+    const base = {
+        input,
+        status: status(spec, "ok"),
+        version,
+        explicitVersion,
+        type,
+        locator,
+        qualifiers,
+        fragment,
+    };
+    if (explicitVersion) {
+        base.versionText = versionText;
+    }
+    const delegated = delegatedString(spec, type, locator);
+    if (delegated !== undefined) {
+        base.delegated = delegated;
+    }
+    if (!spec.version.supported.includes(version)) {
+        return { ...base, status: status(spec, "unsupported") };
+    }
+    // Qualifiers say which state; refinements say which part. The two sides never trade contents.
+    for (const [key] of qualifiers) {
+        if (Object.hasOwn(spec.refinements, key)) {
+            return malformed(spec, input, key, head);
+        }
+    }
+    if (fragment) {
+        for (const [key] of fragment.refinements) {
+            if (Object.hasOwn(spec.qualifiers, key)) {
+                return malformed(spec, input, key, head);
+            }
+        }
+    }
+    const nested = {};
+    for (const [key, value] of qualifiers) {
+        const declared = spec.qualifiers[key];
+        if (!declared) {
+            continue; // spec.grammar.state.unknownKey — carried through untouched, asserted in validators.ts
+        }
+        const result = matchForms(spec, declared.forms, value, depth);
+        if (!result.matches) {
+            return malformed(spec, input, key, head);
+        }
+        if (result.nested !== undefined) {
+            nested[key] = result.nested;
+        }
+    }
+    if (Object.keys(nested).length > 0) {
+        base.nested = nested;
+    }
+    if (fragment) {
+        for (const [key, value] of fragment.refinements) {
+            const declared = spec.refinements[key];
+            if (!declared) {
+                continue; // spec.unknownRefinement — carried through untouched, asserted in validators.ts
+            }
+            if (!pattern(spec, declared.pattern).test(value) || !rangeHolds(declared, value)) {
+                return malformed(spec, input, key, head);
+            }
+        }
+    }
+    const entry = spec.dispatch[type];
+    if (!entry || delegated === undefined) {
+        return { ...base, status: spec.unknownType };
+    }
+    const validation = validateLocator(spec, entry, delegated);
+    if (validation === undefined) {
+        return { ...base, status: spec.unknownType }; // a validator this package does not implement
+    }
+    if (!validation.ok) {
+        return malformed(spec, input, "locator", head);
+    }
+    if (validation.canonical !== undefined) {
+        base.canonical = validation.canonical;
+    }
+    return base;
+}
+/** Parses a `ref:` identifier string against the loaded spec. Never throws for an identifier problem. */
+export function parse(input) {
+    const spec = loadSpec();
+    assertImplemented(spec);
+    if (typeof input !== "string") {
+        // Anything that is not a string is malformed at the grammar; it is not converted, because a
+        // hostile object's conversion can itself throw, and nothing here may throw for an identifier.
+        return malformed(spec, "", "grammar", {});
+    }
+    return parseInternal(spec, input, 0);
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,yFAAyF;AACzF,gGAAgG;AAChG,uEAAuE;AACvE,EAAE;AACF,+FAA+F;AAC/F,mGAAmG;AACnG,iGAAiG;AACjG,iGAAiG;AACjG,6FAA6F;AAC7F,oCAAoC;AAEpC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC5G,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAkB,MAAM,WAAW,CAAA;AAElE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjG,SAAS,SAAS,CAAC,IAAe,EAAE,KAAa,EAAE,UAAkB,EAAE,IAA0B;IAC/F,MAAM,MAAM,GAAgB;QAC1B,KAAK;QACL,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC;QACjC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO;QAC7C,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,KAAK;QAC9C,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE;QACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;QAC/B,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;KAC7B,CAAA;IACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;IACvC,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAID,wGAAwG;AACxG,SAAS,cAAc,CAAC,IAAe,EAAE,OAAe,EAAE,QAAkB,EAAE,UAAkB;IAC9F,MAAM,KAAK,GAAW,EAAE,CAAA;IACxB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;QACxC,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,CAAA;QAClC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;QACjC,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACnC,CAAC;AAED,SAAS,cAAc,CAAC,IAAe,EAAE,GAAW;IAClD,OAAO,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAA;AACvG,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAe,EAAE,GAAW;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC3D,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC9B,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;IACxC,CAAC;IACD,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAA;IAClG,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC;QACpB,OAAO,WAAW,CAAA;IACpB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,EAAE,EAAE,CAAA;AACtE,CAAC;AAED,6GAA6G;AAC7G,SAAS,eAAe,CAAC,KAAa,EAAE,KAA6B;IACnE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAClC,IAAI,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC3B,OAAO,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;YACtD,OAAO,KAAK,CAAA;QACd,CAAC;QACD,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC,CAAA;IACjC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,0HAA0H;AAC1H,SAAS,SAAS,CAAC,IAAe,EAAE,IAAgC,EAAE,KAAa,EAAE,KAAa;IAChG,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAA;IAChC,IAAI,KAAK,IAAI,QAAQ,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC/D,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAClC,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;IAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;IACrD,oGAAoG;IACpG,OAAO,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAA;AACzE,CAAC;AAED,SAAS,UAAU,CACjB,IAAe,EACf,SAA4B,EAC5B,KAAa,EACb,KAAa;IAEb,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,SAAQ;QACV,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;YAClD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;YAClC,CAAC;YACD,SAAQ;QACV,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AAC3B,CAAC;AAED,SAAS,aAAa,CAAC,IAAe,EAAE,KAAa,EAAE,KAAa;IAClE,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC/C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,CAAA;IAC9C,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,MAAM,CAAA;IAEpG,MAAM,eAAe,GAAG,WAAW,KAAK,SAAS,CAAA;IACjD,MAAM,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAA;IAC5E,MAAM,IAAI,GAAyB,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;IAC9E,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAChC,CAAC;IAED,IAAI,UAAU,GAAW,EAAE,CAAA;IAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAC9C,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACtD,CAAC;QACD,UAAU,GAAG,UAAU,CAAC,KAAK,CAAA;IAC/B,CAAC;IACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAE5B,IAAI,QAAQ,GAA0B,IAAI,CAAA;IAC1C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;QACvD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACtD,CAAC;QACD,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAA;IAC7B,CAAC;IACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAExB,MAAM,IAAI,GAAgB;QACxB,KAAK;QACL,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;QAC1B,OAAO;QACP,eAAe;QACf,IAAI;QACJ,OAAO;QACP,UAAU;QACV,QAAQ;KACT,CAAA;IACD,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAChC,CAAC;IACD,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACtD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,CAAA;IACzD,CAAC;IAED,8FAA8F;IAC9F,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,UAAU,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC;YACzC,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;YACzC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CAAC;gBACxC,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,SAAQ,CAAC,uFAAuF;QAClG,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;QAC7D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;QAC1C,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAA;QAC7B,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;YAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;YACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,SAAQ,CAAC,gFAAgF;YAC3F,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;gBACjF,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,CAAC,KAAK,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAA;IAC9C,CAAC;IACD,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;IAC1D,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAA,CAAC,8CAA8C;IAC7F,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;IAChD,CAAC;IACD,IAAI,UAAU,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAA;IACvC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,KAAK,CAAC,KAAa;IACjC,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,iBAAiB,CAAC,IAAI,CAAC,CAAA;IACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,4FAA4F;QAC5F,8FAA8F;QAC9F,OAAO,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,CAAA;IAC3C,CAAC;IACD,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAA;AACtC,CAAC"}

package/dist/serialise.d.ts

@@ -0,0 +1,3 @@
+import type { ParseResult } from "./types.ts";
+/** `serialise(parse(s)) === s` for every parseable input, including uncovered and unsupported ones. A malformed result has no faithful form and is refused. */
+export declare function serialise(parsed: ParseResult): string;

package/dist/serialise.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Reassembles a ParseResult into the exact bytes it was parsed from — the inverse of parse.ts's
+// structural decomposition. Every part is emitted verbatim: the locator, the qualifier values
+// (known and unknown keys alike), the fragment path and its refinements.
+import { SerialiseError } from "./errors.js";
+import { FIELD, FRAGMENT_INTRODUCER, PAIR, schemePrefix } from "./grammar.js";
+import { loadSpec, part, status } from "./spec.js";
+function pairs(entries, separator) {
+    return entries.map(([key, value]) => `${key}${PAIR}${value}`).join(separator);
+}
+/** `serialise(parse(s)) === s` for every parseable input, including uncovered and unsupported ones. A malformed result has no faithful form and is refused. */
+export function serialise(parsed) {
+    const spec = loadSpec();
+    if (parsed.status === status(spec, "malformed")) {
+        throw new SerialiseError(part(spec, parsed.part ?? "grammar"), "a malformed identifier cannot be serialised without losing the part that failed");
+    }
+    let out = schemePrefix(spec);
+    if (parsed.explicitVersion) {
+        out += `${parsed.versionText ?? String(parsed.version)}${FIELD}`;
+    }
+    out += `${parsed.type}${FIELD}${parsed.locator}`;
+    if (parsed.qualifiers.length > 0) {
+        const separator = spec.grammar.state.separator;
+        out += `${separator}${pairs(parsed.qualifiers, separator)}`;
+    }
+    if (parsed.fragment) {
+        out += `${FRAGMENT_INTRODUCER}${parsed.fragment.path}`;
+        if (parsed.fragment.refinements.length > 0) {
+            const separator = spec.grammar.fragment.separator;
+            out += `${separator}${pairs(parsed.fragment.refinements, separator)}`;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=serialise.js.map

package/dist/serialise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialise.js","sourceRoot":"","sources":["../src/serialise.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,gGAAgG;AAChG,8FAA8F;AAC9F,yEAAyE;AAEzE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAGlD,SAAS,KAAK,CAAC,OAAwB,EAAE,SAAiB;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;AAC/E,CAAC;AAED,+JAA+J;AAC/J,MAAM,UAAU,SAAS,CAAC,MAAmB;IAC3C,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,iFAAiF,CAAC,CAAA;IACnJ,CAAC;IAED,IAAI,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QAC3B,GAAG,IAAI,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,EAAE,CAAA;IAClE,CAAC;IACD,GAAG,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;IAEhD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAA;QAC9C,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,CAAA;IAC7D,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,GAAG,IAAI,GAAG,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAA;QACtD,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAA;YACjD,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,CAAA;QACvE,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/spec.d.ts

@@ -0,0 +1,142 @@
+/** Thrown when the loaded spec's bytes do not match its sidecar digest. */
+export declare class SpecIntegrityError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the loaded spec declares a specVersion major, or a vocabulary, this package does not support. */
+export declare class SpecVersionError extends Error {
+    constructor(message: string);
+}
+/**
+ * The `ref:` specification, as published in `spec/ref-id.json`. Typed only as far as the code
+ * reads it; the shapes of the tables and of `vectors` are spec data, read dynamically rather than
+ * mirrored into a second declaration.
+ */
+export interface RefIdSpec {
+    specVersion: string;
+    scheme: string;
+    grammar: {
+        dialect: string;
+        expression: string;
+        groups: string[];
+        adaptations: Record<string, {
+            replace: [string, string][];
+        }>;
+        adaptationsApplyTo: string;
+        anchors: string;
+        state: {
+            separator: string;
+            pair: string;
+            unknownKey: string;
+            repeatedKey: string;
+        };
+        fragment: {
+            separator: string;
+            pair: string;
+            path: string;
+            repeatedKey: string;
+        };
+    };
+    version: {
+        default: number;
+        supported: number[];
+        mints: string[];
+        note: string;
+    };
+    encoding: Record<string, {
+        reserved: string[];
+        table?: Record<string, string>;
+        note?: string;
+    }>;
+    dispatch: Record<string, {
+        locator: string;
+        validator: string;
+        delegate: string;
+        pattern?: string;
+        reference?: string;
+        declaredBy?: string;
+    }>;
+    delegation: Record<string, string>;
+    statuses: string[];
+    parts: string[];
+    unknownType: string;
+    roles: Record<string, string[]>;
+    qualifiers: Record<string, {
+        role: string;
+        forms: string[];
+    }>;
+    forms: Record<string, {
+        pattern?: string;
+        reference?: string;
+        nested?: boolean;
+        depth?: number;
+        encoding?: string;
+        digest?: boolean;
+    }>;
+    refinements: Record<string, {
+        pattern: string;
+        range?: string;
+        boundSeparator?: string;
+        reference?: string;
+    }>;
+    unknownRefinement: string;
+    resolutionStates: string[];
+    stateLevels: string[];
+    fragmentGrammars: Record<string, {
+        declaredName: string;
+        tieBreak: string;
+    }>;
+    digest: {
+        algorithm: string;
+        over: string;
+        order: string;
+        join: string;
+        encoding: string;
+        dedupe: boolean;
+        output: string;
+    };
+    canonicalisation: {
+        form: string;
+        rules: string[];
+        sidecar: string;
+    };
+    envelope: {
+        fields: Record<string, string>;
+        selfReference: string;
+        setsField: string;
+        digestForms: string;
+        invariant: string;
+        onFailure: string;
+    };
+    vectors: {
+        parse: unknown[];
+        roundtrip: string[];
+        build: unknown[];
+        digest: unknown[];
+        envelope: unknown[];
+    };
+}
+/**
+ * Canonical serialisation per `spec.canonicalisation.rules`: object keys sorted by UTF-16 code
+ * unit, no whitespace outside strings, strings escaped as `JSON.stringify` does, numbers
+ * restricted to integers.
+ */
+export declare function canonicalise(value: unknown): string;
+/**
+ * A status name this code needs, checked against the vocabulary the spec declares. Code names a
+ * status because it has to choose one; the spec owns the list, and naming one the spec lacks is a
+ * version mismatch, reported as such rather than silently emitted.
+ */
+export declare function status(spec: RefIdSpec, name: string): string;
+/**
+ * A part name this code needs, checked against the vocabulary the spec declares: one of `spec.parts`,
+ * or a declared qualifier or refinement key (the two placeholders in that list). Same contract as
+ * `status()`: naming a part the spec lacks is a version mismatch, reported rather than emitted.
+ */
+export declare function part(spec: RefIdSpec, name: string): string;
+/**
+ * Loads and validates a spec + sidecar pair from an arbitrary directory. Exposed for the
+ * spec-integrity tests; `loadSpec()` is the entry point every other module uses.
+ */
+export declare function loadSpecFrom(dir: string): RefIdSpec;
+/** The validated spec object, cached after the first successful load. */
+export declare function loadSpec(): RefIdSpec;

package/dist/spec.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Loads spec/ref-id.json, verifies its digest against the sidecar, and checks the specVersion
+// major. Behaviour only — the spec's own data is never restated here.
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+/** Thrown when the loaded spec's bytes do not match its sidecar digest. */
+export class SpecIntegrityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SpecIntegrityError";
+    }
+}
+/** Thrown when the loaded spec declares a specVersion major, or a vocabulary, this package does not support. */
+export class SpecVersionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SpecVersionError";
+    }
+}
+/**
+ * Canonical serialisation per `spec.canonicalisation.rules`: object keys sorted by UTF-16 code
+ * unit, no whitespace outside strings, strings escaped as `JSON.stringify` does, numbers
+ * restricted to integers.
+ */
+export function canonicalise(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new Error(`canonicalisation covers integers only, got ${value}`);
+        }
+        return String(value);
+    }
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalise(item)).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalise(record[key])}`).join(",")}}`;
+    }
+    throw new Error(`value of type ${typeof value} has no canonical form`);
+}
+/** The major version this package was built against. Not spec data — the package's own contract. */
+const SUPPORTED_SPEC_MAJOR = "1";
+function readText(location) {
+    return readFileSync(location, "utf8");
+}
+function validate(rawJson, rawSidecar) {
+    const parsed = JSON.parse(rawJson);
+    const canonical = canonicalise(parsed);
+    const computed = createHash("sha256").update(canonical, "utf8").digest("hex");
+    const expected = rawSidecar.trim();
+    if (computed !== expected) {
+        throw new SpecIntegrityError(`spec/ref-id.json does not match its sidecar digest (expected ${expected}, computed ${computed})`);
+    }
+    const spec = parsed;
+    const major = String(spec.specVersion).split(".")[0];
+    if (major !== SUPPORTED_SPEC_MAJOR) {
+        throw new SpecVersionError(`spec/ref-id.json declares specVersion ${spec.specVersion}; this package supports major ${SUPPORTED_SPEC_MAJOR}`);
+    }
+    return spec;
+}
+/**
+ * A status name this code needs, checked against the vocabulary the spec declares. Code names a
+ * status because it has to choose one; the spec owns the list, and naming one the spec lacks is a
+ * version mismatch, reported as such rather than silently emitted.
+ */
+export function status(spec, name) {
+    if (!spec.statuses.includes(name)) {
+        throw new SpecVersionError(`this package names the status "${name}", which spec ${spec.specVersion} does not declare`);
+    }
+    return name;
+}
+/**
+ * A part name this code needs, checked against the vocabulary the spec declares: one of `spec.parts`,
+ * or a declared qualifier or refinement key (the two placeholders in that list). Same contract as
+ * `status()`: naming a part the spec lacks is a version mismatch, reported rather than emitted.
+ */
+export function part(spec, name) {
+    if (spec.parts.includes(name) || Object.hasOwn(spec.qualifiers, name) || Object.hasOwn(spec.refinements, name)) {
+        return name;
+    }
+    throw new SpecVersionError(`this package names the part "${name}", which spec ${spec.specVersion} does not declare`);
+}
+/**
+ * Loads and validates a spec + sidecar pair from an arbitrary directory. Exposed for the
+ * spec-integrity tests; `loadSpec()` is the entry point every other module uses.
+ */
+export function loadSpecFrom(dir) {
+    const raw = readText(`${dir}/ref-id.json`);
+    const sidecar = readText(`${dir}/ref-id.json.sha256`);
+    return validate(raw, sidecar);
+}
+let cached;
+/** The validated spec object, cached after the first successful load. */
+export function loadSpec() {
+    if (cached) {
+        return cached;
+    }
+    const jsonUrl = new URL("../spec/ref-id.json", import.meta.url);
+    const sidecarUrl = new URL("../spec/ref-id.json.sha256", import.meta.url);
+    const raw = readText(jsonUrl);
+    const sidecar = readText(sidecarUrl);
+    cached = validate(raw, sidecar);
+    return cached;
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/** A `key=value` pair, in the order it appeared in the input, values kept verbatim. */
+export type Pair = [key: string, value: string];
+/** One of `spec.statuses` — the vocabulary is data, so the type is open. */
+export type ParseStatus = string;
+export interface ParsedFragment {
+    path: string;
+    refinements: Pair[];
+}
+export interface ParseResult {
+    input: string;
+    status: ParseStatus;
+    version: number;
+    explicitVersion: boolean;
+    /** The version token as written, when explicit — so that serialising returns the same bytes. */
+    versionText?: string;
+    type: string;
+    /** The captured group, verbatim. */
+    locator: string;
+    /** The string handed to the owning validator, formed per `dispatch.<type>.delegate`; absent when the type is not dispatched. */
+    delegated?: string;
+    /** The validator's own canonical spelling of `delegated`, when the format defines one. Informational; identity is the string. */
+    canonical?: string;
+    qualifiers: Pair[];
+    /** The decoded identifier behind each qualifier value that nests one. */
+    nested?: Record<string, string>;
+    fragment: ParsedFragment | null;
+    /** On `malformed`: which part failed — one of `spec.parts`. */
+    part?: string;
+}
+export type NestedQualifierValue = {
+    nested: string;
+};
+export interface BuildParts {
+    type: string;
+    /** For a type-prefixed dispatch, either the bare group (`npm/x@1.0.0`) or the intact format string (`pkg:npm/x@1.0.0`). */
+    locator: string;
+    qualifiers?: [key: string, value: string | NestedQualifierValue][];
+    fragment?: string | {
+        path: string;
+        refinements?: Pair[];
+    };
+    /** Never reaches the identifier — location is an attribute of the node, not its name. */
+    location?: unknown;
+}
+export interface EnvelopeResult {
+    admissible: boolean;
+    reason?: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC"}

package/dist/validators.d.ts

@@ -0,0 +1,19 @@
+import { type RefIdSpec } from "./spec.ts";
+export type Validation = {
+    ok: true;
+    canonical?: string;
+} | {
+    ok: false;
+};
+type DispatchEntry = RefIdSpec["dispatch"][string];
+/** Refuses a spec whose declared policies or range names are ones this package does not implement. */
+export declare function assertImplemented(spec: RefIdSpec): void;
+/** The string handed to the validator, or undefined when the type is not dispatched or its delegate mode is unknown here. */
+export declare function delegatedString(spec: RefIdSpec, type: string, locator: string): string | undefined;
+/** True when a producer may pass the intact format string (`pkg:npm/x`) as the locator of this type. */
+export declare function foldsType(spec: RefIdSpec, type: string): boolean;
+/** Runs the owning validator, or undefined when the spec names one this package does not implement. */
+export declare function validateLocator(spec: RefIdSpec, entry: DispatchEntry, delegated: string): Validation | undefined;
+/** True when the value satisfies the refinement's declared range constraint (or it declares none). */
+export declare function rangeHolds(refinement: RefIdSpec["refinements"][string], value: string): boolean;
+export {};