@maroonedog/luq 0.1.2-alpha → 2.1.0

package/dist/json-schema/keyword-map.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_DRAFT07_KEYWORDS = exports.draft07KeywordMap = void 0;
+exports.isDraft07Keyword = isDraft07Keyword;
+exports.listDraft07Keywords = listDraft07Keywords;
+exports.findKeywordHandling = findKeywordHandling;
+exports.assertKeywordSupported = assertKeywordSupported;
+exports.listBoundPluginNames = listBoundPluginNames;
+exports.countKeywordHandlings = countKeywordHandlings;
+const keyword_map_core_1 = require("./keyword-map-core");
+const keyword_map_number_1 = require("./keyword-map-number");
+const keyword_map_string_1 = require("./keyword-map-string");
+const keyword_map_array_1 = require("./keyword-map-array");
+const keyword_map_object_1 = require("./keyword-map-object");
+const format_map_1 = require("./format-map");
+const unsupported_keyword_error_1 = require("./unsupported-keyword-error");
+exports.draft07KeywordMap = {
+    ...keyword_map_core_1.coreKeywordMap,
+    ...keyword_map_number_1.numberKeywordMap,
+    ...keyword_map_string_1.stringKeywordMap,
+    ...keyword_map_array_1.arrayKeywordMap,
+    ...keyword_map_object_1.objectKeywordMap,
+};
+/**
+ * Keywords Luq recognises the NAME of but which are not Draft-07. They are
+ * listed so that "we did not implement it" and "it is not in this dialect"
+ * stay different answers. `$defs` is the one exception that still does
+ * something: resolve-ref follows it, because a 2019-09 document's pointers
+ * would otherwise dangle.
+ */
+exports.NON_DRAFT07_KEYWORDS = {
+    $defs: "2019-09 spelling of `definitions`; resolve-ref follows it anyway",
+    $anchor: "2019-09 anchors; resolve-ref resolves JSON Pointers only",
+    $dynamicRef: "2020-12 dynamic references",
+    $recursiveRef: "2019-09 recursive references",
+    dependentRequired: "2019-09 split of `dependencies`; use `dependencies`",
+    dependentSchemas: "2019-09 split of `dependencies`; use `dependencies`",
+    unevaluatedItems: "2019-09; no annotation-collection model in Luq",
+    unevaluatedProperties: "2019-09; no annotation-collection model in Luq",
+    contentSchema: "2019-09 companion to contentMediaType",
+    deprecated: "2019-09 annotation",
+    prefixItems: "2020-12 spelling of the tuple form of `items`",
+};
+function isDraft07Keyword(keyword) {
+    return Object.prototype.hasOwnProperty.call(exports.draft07KeywordMap, keyword);
+}
+/** Every keyword the table decides on. No assertion; the guard narrows. */
+function listDraft07Keywords() {
+    return Object.keys(exports.draft07KeywordMap).filter(isDraft07Keyword);
+}
+/** `undefined` = not a Draft-07 keyword at all. See NON_DRAFT07_KEYWORDS. */
+function findKeywordHandling(keyword) {
+    return isDraft07Keyword(keyword) ? exports.draft07KeywordMap[keyword] : undefined;
+}
+/** Throws for a keyword the table declares out of scope. Never silent. */
+function assertKeywordSupported(keyword) {
+    const handling = findKeywordHandling(keyword);
+    if (handling === undefined) {
+        const note = exports.NON_DRAFT07_KEYWORDS[keyword];
+        throw new unsupported_keyword_error_1.UnsupportedKeywordError(keyword, note ?? "not a Draft-07 keyword");
+    }
+    if (handling.handling === "unsupported") {
+        throw new unsupported_keyword_error_1.UnsupportedKeywordError(keyword, handling.reason);
+    }
+}
+/**
+ * Every plugin the two tables bind, de-duplicated and sorted. Step 26 GENERATES
+ * the full-feature bundle's use() list from this, so the bundle cannot name a
+ * plugin that is not bound, and cannot omit one that is.
+ */
+function listBoundPluginNames() {
+    const names = new Set();
+    const handlings = [
+        ...Object.values(exports.draft07KeywordMap),
+        ...Object.values(format_map_1.draft07FormatMap),
+    ];
+    for (const handling of handlings) {
+        if (handling.handling === "bind")
+            names.add(handling.pluginName);
+    }
+    return [...names].sort();
+}
+/** Counted, never asserted: the published numbers come from this function. */
+function countKeywordHandlings(table) {
+    const entries = Object.values(table);
+    const countOf = (kind) => entries.filter((handling) => handling.handling === kind).length;
+    return {
+        bind: countOf("bind"),
+        structural: countOf("structural"),
+        unsupported: countOf("unsupported"),
+        total: entries.length,
+    };
+}

package/dist/json-schema/keyword-map.mjs

@@ -0,0 +1,84 @@
+import { coreKeywordMap } from "./keyword-map-core.mjs";
+import { numberKeywordMap } from "./keyword-map-number.mjs";
+import { stringKeywordMap } from "./keyword-map-string.mjs";
+import { arrayKeywordMap } from "./keyword-map-array.mjs";
+import { objectKeywordMap } from "./keyword-map-object.mjs";
+import { draft07FormatMap } from "./format-map.mjs";
+import { UnsupportedKeywordError } from "./unsupported-keyword-error.mjs";
+export const draft07KeywordMap = {
+    ...coreKeywordMap,
+    ...numberKeywordMap,
+    ...stringKeywordMap,
+    ...arrayKeywordMap,
+    ...objectKeywordMap,
+};
+/**
+ * Keywords Luq recognises the NAME of but which are not Draft-07. They are
+ * listed so that "we did not implement it" and "it is not in this dialect"
+ * stay different answers. `$defs` is the one exception that still does
+ * something: resolve-ref follows it, because a 2019-09 document's pointers
+ * would otherwise dangle.
+ */
+export const NON_DRAFT07_KEYWORDS = {
+    $defs: "2019-09 spelling of `definitions`; resolve-ref follows it anyway",
+    $anchor: "2019-09 anchors; resolve-ref resolves JSON Pointers only",
+    $dynamicRef: "2020-12 dynamic references",
+    $recursiveRef: "2019-09 recursive references",
+    dependentRequired: "2019-09 split of `dependencies`; use `dependencies`",
+    dependentSchemas: "2019-09 split of `dependencies`; use `dependencies`",
+    unevaluatedItems: "2019-09; no annotation-collection model in Luq",
+    unevaluatedProperties: "2019-09; no annotation-collection model in Luq",
+    contentSchema: "2019-09 companion to contentMediaType",
+    deprecated: "2019-09 annotation",
+    prefixItems: "2020-12 spelling of the tuple form of `items`",
+};
+export function isDraft07Keyword(keyword) {
+    return Object.prototype.hasOwnProperty.call(draft07KeywordMap, keyword);
+}
+/** Every keyword the table decides on. No assertion; the guard narrows. */
+export function listDraft07Keywords() {
+    return Object.keys(draft07KeywordMap).filter(isDraft07Keyword);
+}
+/** `undefined` = not a Draft-07 keyword at all. See NON_DRAFT07_KEYWORDS. */
+export function findKeywordHandling(keyword) {
+    return isDraft07Keyword(keyword) ? draft07KeywordMap[keyword] : undefined;
+}
+/** Throws for a keyword the table declares out of scope. Never silent. */
+export function assertKeywordSupported(keyword) {
+    const handling = findKeywordHandling(keyword);
+    if (handling === undefined) {
+        const note = NON_DRAFT07_KEYWORDS[keyword];
+        throw new UnsupportedKeywordError(keyword, note ?? "not a Draft-07 keyword");
+    }
+    if (handling.handling === "unsupported") {
+        throw new UnsupportedKeywordError(keyword, handling.reason);
+    }
+}
+/**
+ * Every plugin the two tables bind, de-duplicated and sorted. Step 26 GENERATES
+ * the full-feature bundle's use() list from this, so the bundle cannot name a
+ * plugin that is not bound, and cannot omit one that is.
+ */
+export function listBoundPluginNames() {
+    const names = new Set();
+    const handlings = [
+        ...Object.values(draft07KeywordMap),
+        ...Object.values(draft07FormatMap),
+    ];
+    for (const handling of handlings) {
+        if (handling.handling === "bind")
+            names.add(handling.pluginName);
+    }
+    return [...names].sort();
+}
+/** Counted, never asserted: the published numbers come from this function. */
+export function countKeywordHandlings(table) {
+    const entries = Object.values(table);
+    const countOf = (kind) => entries.filter((handling) => handling.handling === kind).length;
+    return {
+        bind: countOf("bind"),
+        structural: countOf("structural"),
+        unsupported: countOf("unsupported"),
+        total: entries.length,
+    };
+}

package/dist/json-schema/ref-resolution-error.d.ts

@@ -0,0 +1,4 @@
+export declare class RefResolutionError extends Error {
+    readonly ref: string;
+    constructor(ref: string, reason: string);
+}

package/dist/json-schema/ref-resolution-error.js

@@ -0,0 +1,20 @@
+"use strict";
+// ===========================================================================
+// L8  src/json-schema/ref-resolution-error.ts
+//
+// `$ref` が解けなかったことを表す例外。呼び出し側が **identity で捕まえられる**
+// ことが要件なので、独立したクラスであり、独立したモジュールである
+// (resolve-ref.ts から import すると、その巨大な依存を一緒に引く)。
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefResolutionError = void 0;
+class RefResolutionError extends Error {
+    constructor(ref, reason) {
+        super(`Cannot resolve $ref "${ref}": ${reason}`);
+        this.name = "RefResolutionError";
+        this.ref = ref;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, RefResolutionError.prototype);
+    }
+}
+exports.RefResolutionError = RefResolutionError;

package/dist/json-schema/ref-resolution-error.mjs

@@ -0,0 +1,16 @@
+// ===========================================================================
+// L8  src/json-schema/ref-resolution-error.ts
+//
+// `$ref` が解けなかったことを表す例外。呼び出し側が **identity で捕まえられる**
+// ことが要件なので、独立したクラスであり、独立したモジュールである
+// (resolve-ref.ts から import すると、その巨大な依存を一緒に引く)。
+// ===========================================================================
+export class RefResolutionError extends Error {
+    constructor(ref, reason) {
+        super(`Cannot resolve $ref "${ref}": ${reason}`);
+        this.name = "RefResolutionError";
+        this.ref = ref;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, RefResolutionError.prototype);
+    }
+}

package/dist/json-schema/ref-scope.d.ts

@@ -0,0 +1,18 @@
+import type { Draft07Schema } from "./draft07.types";
+import type { SchemaRegistry } from "./schema-registry";
+export interface RefScope {
+    /** The resource a fragment-only reference (`#/definitions/x`) resolves in. */
+    readonly document: Draft07Schema;
+    /** The base URI in force here, "" for a document that declares no `$id`. */
+    readonly baseUri: string;
+    /** Everything a URI can name: `$id` bases, anchors, supplied documents. */
+    readonly registry: SchemaRegistry;
+}
+/**
+ * The scope of a document that declares no `$id` and reaches nothing else.
+ * Used by callers that hold a root and nothing more, and by every test that
+ * is about pointers rather than about identity.
+ */
+export declare function createLocalScope(root: Draft07Schema): RefScope;
+/** A scope over a root plus the documents the caller already loaded. */
+export declare function createDocumentScope(root: Draft07Schema, externalDocuments: Readonly<Record<string, unknown>>): RefScope;

package/dist/json-schema/ref-scope.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalScope = createLocalScope;
+exports.createDocumentScope = createDocumentScope;
+const draft07_types_1 = require("./draft07.types");
+const schema_registry_1 = require("./schema-registry");
+const uri_reference_1 = require("./uri-reference");
+/**
+ * A document's own `$id` is where its base URI starts. Beginning at "" and
+ * ignoring it is how `{"$id":"http://host/a","properties":{"x":{"$ref":"b.json"}}}`
+ * ends up looking for a document literally named "b.json".
+ */
+function baseUriOf(root) {
+    if (!(0, draft07_types_1.isSchemaObject)(root) || typeof root.$id !== "string")
+        return "";
+    return (0, uri_reference_1.nextBaseUri)("", root.$id);
+}
+/**
+ * The scope of a document that declares no `$id` and reaches nothing else.
+ * Used by callers that hold a root and nothing more, and by every test that
+ * is about pointers rather than about identity.
+ */
+function createLocalScope(root) {
+    return {
+        document: root,
+        baseUri: baseUriOf(root),
+        registry: (0, schema_registry_1.createSchemaRegistry)(root),
+    };
+}
+/** A scope over a root plus the documents the caller already loaded. */
+function createDocumentScope(root, externalDocuments) {
+    return {
+        document: root,
+        baseUri: baseUriOf(root),
+        registry: (0, schema_registry_1.createSchemaRegistry)(root, externalDocuments),
+    };
+}

package/dist/json-schema/ref-scope.mjs

@@ -0,0 +1,33 @@
+import { isSchemaObject } from "./draft07.types.mjs";
+import { createSchemaRegistry } from "./schema-registry.mjs";
+import { nextBaseUri } from "./uri-reference.mjs";
+/**
+ * A document's own `$id` is where its base URI starts. Beginning at "" and
+ * ignoring it is how `{"$id":"http://host/a","properties":{"x":{"$ref":"b.json"}}}`
+ * ends up looking for a document literally named "b.json".
+ */
+function baseUriOf(root) {
+    if (!isSchemaObject(root) || typeof root.$id !== "string")
+        return "";
+    return nextBaseUri("", root.$id);
+}
+/**
+ * The scope of a document that declares no `$id` and reaches nothing else.
+ * Used by callers that hold a root and nothing more, and by every test that
+ * is about pointers rather than about identity.
+ */
+export function createLocalScope(root) {
+    return {
+        document: root,
+        baseUri: baseUriOf(root),
+        registry: createSchemaRegistry(root),
+    };
+}
+/** A scope over a root plus the documents the caller already loaded. */
+export function createDocumentScope(root, externalDocuments) {
+    return {
+        document: root,
+        baseUri: baseUriOf(root),
+        registry: createSchemaRegistry(root, externalDocuments),
+    };
+}

package/dist/json-schema/resolve-ref.d.ts

@@ -0,0 +1,21 @@
+import type { Draft07Schema } from "./draft07.types";
+import type { RefScope } from "./ref-scope";
+/**
+ * Resolves `ref` in `scope`, then keeps following `$ref` until it reaches a
+ * schema that is not one. `visited` holds the ABSOLUTE URIs already entered on
+ * THIS chain, so `a -> b -> a` throws instead of looping forever — absolute,
+ * because two different bases can spell the same target differently and a
+ * relative comparison would miss the cycle.
+ */
+export declare function resolveRefInScope(ref: string, scope: RefScope): {
+    schema: Draft07Schema;
+    scope: RefScope;
+};
+/** The local-only door, kept for callers that have nothing but a root. */
+export declare function resolveRef(ref: string, root: Draft07Schema): Draft07Schema;
+/**
+ * True when `ref` resolves without leaving what the caller supplied and
+ * without entering a cycle. It answers the question without making the caller
+ * catch to find out.
+ */
+export declare function isResolvableRef(ref: string, root: Draft07Schema): boolean;

package/dist/json-schema/resolve-ref.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRefInScope = resolveRefInScope;
+exports.resolveRef = resolveRef;
+exports.isResolvableRef = isResolvableRef;
+const ref_resolution_error_1 = require("./ref-resolution-error");
+const draft07_types_1 = require("./draft07.types");
+const collect_definitions_1 = require("./collect-definitions");
+const follow_json_pointer_1 = require("./follow-json-pointer");
+const ref_scope_1 = require("./ref-scope");
+const uri_reference_1 = require("./uri-reference");
+/** No legitimate document chains this many `$ref`s. See resolveRef. */
+const MAX_REF_HOPS = 1000;
+function followPointer(ref, fragment, scope) {
+    const walked = (0, follow_json_pointer_1.walkPointer)(fragment, scope.document, scope, (at, node) => (0, draft07_types_1.isDraft07Schema)(node) && (0, draft07_types_1.isSchemaObject)(node)
+        ? (0, collect_definitions_1.advanceBase)(at, node)
+        : at, (token) => {
+        throw new ref_resolution_error_1.RefResolutionError(ref, `no schema at segment "${token}"`);
+    });
+    if (!(0, draft07_types_1.isDraft07Schema)(walked.node)) {
+        throw new ref_resolution_error_1.RefResolutionError(ref, "the target is not a schema");
+    }
+    return { schema: walked.node, scope: walked.scope };
+}
+/** True for `#name`: a plain-name fragment, which names rather than locates. */
+function isPlainNameFragment(fragment) {
+    return fragment !== "" && !fragment.startsWith("/");
+}
+/**
+ * One hop. The returned scope's `document` is the RESOURCE the target was
+ * found in, never the target itself — otherwise `a -> b` would resolve `b`
+ * against the node `a` names, and a two-link chain of local pointers stops
+ * finding anything after the first hop.
+ */
+function stepRef(ref, scope) {
+    const absolute = (0, uri_reference_1.resolveUriReference)(scope.baseUri, ref);
+    const { resource, fragment } = (0, uri_reference_1.splitUri)(absolute);
+    if (isPlainNameFragment(fragment)) {
+        const named = scope.registry.findIdentified(absolute);
+        if (named === undefined) {
+            throw new ref_resolution_error_1.RefResolutionError(ref, `no schema is named "${absolute}"`);
+        }
+        return {
+            schema: named.schema,
+            scope: {
+                registry: scope.registry,
+                document: named.document,
+                baseUri: named.baseUri,
+            },
+        };
+    }
+    const target = resolveResource(ref, resource, scope);
+    // The RESOURCE's retrieval URI wins over any `$id` the document carries —
+    // "retrieved nested refs resolve relative to their URI not $id" in the
+    // suite is exactly that. Every `$id` INSIDE it still counts, and
+    // followPointer collects them as it walks.
+    const landed = {
+        registry: scope.registry,
+        document: target.document,
+        baseUri: target.baseUri,
+    };
+    return followPointer(ref, fragment, landed);
+}
+/**
+ * The DOCUMENT a resource URI names. An empty resource is "the document this
+ * reference was written in", which is what makes `#/definitions/x` local.
+ */
+function resolveResource(ref, resource, scope) {
+    if (resource === "" || resource === scope.baseUri) {
+        return { document: scope.document, baseUri: scope.baseUri };
+    }
+    const identified = scope.registry.findIdentified(resource);
+    if (identified === undefined || !(0, draft07_types_1.isSchemaObject)(identified.document)) {
+        // The one place an external reference is refused, and it is refused for
+        // ONE reason: nobody handed Luq that document. Luq does not go and get it.
+        throw new ref_resolution_error_1.RefResolutionError(ref, `"${resource}" was not supplied. Luq never fetches a schema; pass it ` +
+            "in externalDocuments.");
+    }
+    return { document: identified.document, baseUri: identified.baseUri };
+}
+/**
+ * Resolves `ref` in `scope`, then keeps following `$ref` until it reaches a
+ * schema that is not one. `visited` holds the ABSOLUTE URIs already entered on
+ * THIS chain, so `a -> b -> a` throws instead of looping forever — absolute,
+ * because two different bases can spell the same target differently and a
+ * relative comparison would miss the cycle.
+ */
+function resolveRefInScope(ref, scope) {
+    const visited = new Set();
+    let current = scope;
+    let currentRef = ref;
+    for (let hop = 0;; hop += 1) {
+        // The visited set is the real cycle detector and gives the good message.
+        // This bound is the SECOND line: a synchronous infinite loop cannot be
+        // interrupted by a test timeout, so a defect in the detector above must
+        // still terminate. Measured: removing the visited check without this made
+        // the resolver hang the whole test process instead of failing it.
+        if (hop > MAX_REF_HOPS) {
+            throw new ref_resolution_error_1.RefResolutionError(ref, `more than ${MAX_REF_HOPS} $ref hops`);
+        }
+        const absolute = (0, uri_reference_1.resolveUriReference)(current.baseUri, currentRef);
+        if (visited.has(absolute)) {
+            throw new ref_resolution_error_1.RefResolutionError(ref, `circular reference: ${[...visited, absolute].join(" -> ")}`);
+        }
+        visited.add(absolute);
+        const step = stepRef(currentRef, current);
+        current = step.scope;
+        if (!(0, draft07_types_1.isSchemaObject)(step.schema) || step.schema.$ref === undefined) {
+            return { schema: step.schema, scope: current };
+        }
+        currentRef = step.schema.$ref;
+    }
+}
+/** The local-only door, kept for callers that have nothing but a root. */
+function resolveRef(ref, root) {
+    return resolveRefInScope(ref, (0, ref_scope_1.createLocalScope)(root)).schema;
+}
+/**
+ * True when `ref` resolves without leaving what the caller supplied and
+ * without entering a cycle. It answers the question without making the caller
+ * catch to find out.
+ */
+function isResolvableRef(ref, root) {
+    try {
+        resolveRef(ref, root);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof ref_resolution_error_1.RefResolutionError)
+            return false;
+        throw error;
+    }
+}

package/dist/json-schema/resolve-ref.mjs

@@ -0,0 +1,128 @@
+import { RefResolutionError } from "./ref-resolution-error.mjs";
+import { isDraft07Schema, isSchemaObject } from "./draft07.types.mjs";
+import { advanceBase } from "./collect-definitions.mjs";
+import { walkPointer } from "./follow-json-pointer.mjs";
+import { createLocalScope } from "./ref-scope.mjs";
+import { resolveUriReference, splitUri } from "./uri-reference.mjs";
+/** No legitimate document chains this many `$ref`s. See resolveRef. */
+const MAX_REF_HOPS = 1000;
+function followPointer(ref, fragment, scope) {
+    const walked = walkPointer(fragment, scope.document, scope, (at, node) => isDraft07Schema(node) && isSchemaObject(node)
+        ? advanceBase(at, node)
+        : at, (token) => {
+        throw new RefResolutionError(ref, `no schema at segment "${token}"`);
+    });
+    if (!isDraft07Schema(walked.node)) {
+        throw new RefResolutionError(ref, "the target is not a schema");
+    }
+    return { schema: walked.node, scope: walked.scope };
+}
+/** True for `#name`: a plain-name fragment, which names rather than locates. */
+function isPlainNameFragment(fragment) {
+    return fragment !== "" && !fragment.startsWith("/");
+}
+/**
+ * One hop. The returned scope's `document` is the RESOURCE the target was
+ * found in, never the target itself — otherwise `a -> b` would resolve `b`
+ * against the node `a` names, and a two-link chain of local pointers stops
+ * finding anything after the first hop.
+ */
+function stepRef(ref, scope) {
+    const absolute = resolveUriReference(scope.baseUri, ref);
+    const { resource, fragment } = splitUri(absolute);
+    if (isPlainNameFragment(fragment)) {
+        const named = scope.registry.findIdentified(absolute);
+        if (named === undefined) {
+            throw new RefResolutionError(ref, `no schema is named "${absolute}"`);
+        }
+        return {
+            schema: named.schema,
+            scope: {
+                registry: scope.registry,
+                document: named.document,
+                baseUri: named.baseUri,
+            },
+        };
+    }
+    const target = resolveResource(ref, resource, scope);
+    // The RESOURCE's retrieval URI wins over any `$id` the document carries —
+    // "retrieved nested refs resolve relative to their URI not $id" in the
+    // suite is exactly that. Every `$id` INSIDE it still counts, and
+    // followPointer collects them as it walks.
+    const landed = {
+        registry: scope.registry,
+        document: target.document,
+        baseUri: target.baseUri,
+    };
+    return followPointer(ref, fragment, landed);
+}
+/**
+ * The DOCUMENT a resource URI names. An empty resource is "the document this
+ * reference was written in", which is what makes `#/definitions/x` local.
+ */
+function resolveResource(ref, resource, scope) {
+    if (resource === "" || resource === scope.baseUri) {
+        return { document: scope.document, baseUri: scope.baseUri };
+    }
+    const identified = scope.registry.findIdentified(resource);
+    if (identified === undefined || !isSchemaObject(identified.document)) {
+        // The one place an external reference is refused, and it is refused for
+        // ONE reason: nobody handed Luq that document. Luq does not go and get it.
+        throw new RefResolutionError(ref, `"${resource}" was not supplied. Luq never fetches a schema; pass it ` +
+            "in externalDocuments.");
+    }
+    return { document: identified.document, baseUri: identified.baseUri };
+}
+/**
+ * Resolves `ref` in `scope`, then keeps following `$ref` until it reaches a
+ * schema that is not one. `visited` holds the ABSOLUTE URIs already entered on
+ * THIS chain, so `a -> b -> a` throws instead of looping forever — absolute,
+ * because two different bases can spell the same target differently and a
+ * relative comparison would miss the cycle.
+ */
+export function resolveRefInScope(ref, scope) {
+    const visited = new Set();
+    let current = scope;
+    let currentRef = ref;
+    for (let hop = 0;; hop += 1) {
+        // The visited set is the real cycle detector and gives the good message.
+        // This bound is the SECOND line: a synchronous infinite loop cannot be
+        // interrupted by a test timeout, so a defect in the detector above must
+        // still terminate. Measured: removing the visited check without this made
+        // the resolver hang the whole test process instead of failing it.
+        if (hop > MAX_REF_HOPS) {
+            throw new RefResolutionError(ref, `more than ${MAX_REF_HOPS} $ref hops`);
+        }
+        const absolute = resolveUriReference(current.baseUri, currentRef);
+        if (visited.has(absolute)) {
+            throw new RefResolutionError(ref, `circular reference: ${[...visited, absolute].join(" -> ")}`);
+        }
+        visited.add(absolute);
+        const step = stepRef(currentRef, current);
+        current = step.scope;
+        if (!isSchemaObject(step.schema) || step.schema.$ref === undefined) {
+            return { schema: step.schema, scope: current };
+        }
+        currentRef = step.schema.$ref;
+    }
+}
+/** The local-only door, kept for callers that have nothing but a root. */
+export function resolveRef(ref, root) {
+    return resolveRefInScope(ref, createLocalScope(root)).schema;
+}
+/**
+ * True when `ref` resolves without leaving what the caller supplied and
+ * without entering a cycle. It answers the question without making the caller
+ * catch to find out.
+ */
+export function isResolvableRef(ref, root) {
+    try {
+        resolveRef(ref, root);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof RefResolutionError)
+            return false;
+        throw error;
+    }
+}

package/dist/json-schema/schema-registry.d.ts

@@ -0,0 +1,30 @@
+import type { Draft07Schema } from "./draft07.types";
+/**
+ * A node the index names, with the base URI in force inside it and the
+ * DOCUMENT that base belongs to.
+ *
+ * The document is not always the node. `$id: "#name"` names a sub-schema
+ * without starting a new resource, so a `#/definitions/x` written next to it
+ * still has to resolve against the enclosing document — resolving it against
+ * the anchored sub-schema instead is how a chain of refs silently stops
+ * finding anything after the first hop.
+ */
+export interface RegisteredTarget {
+    readonly schema: Draft07Schema;
+    readonly baseUri: string;
+    readonly document: Draft07Schema;
+}
+export interface SchemaRegistry {
+    /** The node this absolute URI NAMES — a document `$id`, or an anchor. */
+    findIdentified(uri: string): RegisteredTarget | undefined;
+}
+/**
+ * Every `$id` in `root` and in each supplied external document.
+ *
+ * The external map's KEY is a URI in its own right: the suite (and real
+ * callers) fetch `http://host/a.json` into a document that does not repeat its
+ * own `$id`, so the key is what a `$ref` will name. A document that DOES carry
+ * `$id` registers that too, and the `$id` wins where they disagree — it is the
+ * document's own statement about its identity.
+ */
+export declare function createSchemaRegistry(root: Draft07Schema, externalDocuments?: Readonly<Record<string, unknown>>): SchemaRegistry;