@maroonedog/luq 2.0.0 → 2.2.0

package/dist/json-schema/index.mjs

@@ -5,14 +5,17 @@
 // the only json-schema surface anything outside src/json-schema/ may reach.
 // ===========================================================================
 export { NotASchemaError, buildFieldEntries, buildFromSchema, fromJsonSchema, } from "./build-from-schema.mjs";
-export { DEFINITION_CONTAINERS, collectDefinitionNames, isDefinitionContainer, readRefPointer, resolveSchemaNode, toSchemaObject, } from "./collect-definitions.mjs";
+export { DEFINITION_CONTAINERS, collectDefinitionNames, isDefinitionContainer, readRefPointer, resolveSchemaNode, resolveSchemaNodeInScope, toSchemaObject, } from "./collect-definitions.mjs";
 export { flattenSchema, joinDeclaredPath } from "./flatten-schema.mjs";
 export { STRUCTURAL_EXPANSIONS, expandSchemaRules, isStructuralKeyword, readChildSchemas, } from "./schema-to-declarations.mjs";
 export { collectSubSchemaRules, toSchemaBranch, } from "./collect-sub-schema-rules.mjs";
 export { createStructuralContext } from "./create-structural-context.mjs";
 export { declareRequiredProperties } from "./declare-required-properties.mjs";
 export { declarePresenceRules } from "./declare-presence.mjs";
-export { RefResolutionError, isResolvableRef, resolveRef } from "./resolve-ref.mjs";
+export { RefResolutionError } from "./ref-resolution-error.mjs";
+export { isResolvableRef, resolveRef, resolveRefInScope } from "./resolve-ref.mjs";
+export { createDocumentScope, createLocalScope } from "./ref-scope.mjs";
+export { createSchemaRegistry } from "./schema-registry.mjs";
 export { UnsupportedKeywordError } from "./unsupported-keyword-error.mjs";
 export { isDraft07Schema, isSchemaObject } from "./draft07.types.mjs";
 export { assertKeywordSupported, countKeywordHandlings, findKeywordHandling, isDraft07Keyword, listBoundPluginNames, listDraft07Keywords, } from "./keyword-map.mjs";

package/dist/json-schema/keyword-map-object.d.ts

@@ -13,5 +13,5 @@ export declare const requiredBinding: import("./keyword-binding.types").KeywordB
  * to the declared sibling keys, so `additionalProperties: false` no longer
  * rejects every property the way 1.x's empty `allowedProperties` default did.
  */
-export declare const additionalPropertiesBinding: import("./keyword-binding.types").KeywordBinding<"object", "additionalProperties", "objectAdditionalProperties", readonly [allowed: boolean, allowedProperties?: readonly string[] | undefined], boolean>;
+export declare const additionalPropertiesBinding: import("./keyword-binding.types").KeywordBinding<"object", "additionalProperties", "objectAdditionalProperties", readonly [allowed: boolean, allowedProperties?: readonly string[] | undefined, allowedPatterns?: readonly string[] | undefined], boolean>;
 export declare const objectKeywordMap: KeywordTable<Draft07ObjectKeyword>;

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

@@ -1,16 +1,21 @@
 import type { Draft07Schema } from "./draft07.types";
-export declare class RefResolutionError extends Error {
-    readonly ref: string;
-    constructor(ref: string, reason: string);
-}
+import type { RefScope } from "./ref-scope";
 /**
- * Resolves `ref` against `root`, then keeps following `$ref` until it reaches
- * a schema that is not one. `visited` holds the pointers already entered on
- * THIS chain, so `a -> b -> a` throws instead of looping forever.
+ * 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 the document and without entering a
- * cycle. It answers the question without making the caller catch to find out.
+ * 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

@@ -1,68 +1,93 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RefResolutionError = void 0;
+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 types_1 = require("../types");
-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;
+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;
-/** RFC 6901: `~1` is "/" and `~0` is "~", decoded in that order. */
-function decodePointerToken(token) {
-    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+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 };
 }
-function toPointerTokens(ref) {
-    const pointer = ref.slice(1);
-    if (pointer === "" || pointer === "/")
-        return [];
-    return pointer.split("/").slice(1).map(decodePointerToken);
+/** True for `#name`: a plain-name fragment, which names rather than locates. */
+function isPlainNameFragment(fragment) {
+    return fragment !== "" && !fragment.startsWith("/");
 }
 /**
- * `definitions` and `$defs` are the same container to a pointer: a Draft-07
- * document spells it one way, a 2019-09 document the other, and a schema that
- * mixes them (they exist) must still resolve. A real `definitions` member
- * always wins, so a property literally named "definitions" is unaffected.
+ * 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 stepInto(current, token) {
-    if ((0, types_1.isArray)(current))
-        return current[Number(token)];
-    if (!(0, types_1.isPlainObject)(current))
-        return undefined;
-    if (token === "definitions" || token === "$defs") {
-        return current["definitions"] ?? current["$defs"];
+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,
+            },
+        };
     }
-    return current[token];
+    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);
 }
-function followPointer(ref, root) {
-    let current = root;
-    for (const token of toPointerTokens(ref)) {
-        current = stepInto(current, token);
-        if (current === undefined) {
-            throw new RefResolutionError(ref, `no schema at segment "${token}"`);
-        }
+/**
+ * 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 };
     }
-    if (!(0, draft07_types_1.isDraft07Schema)(current)) {
-        throw new RefResolutionError(ref, "the target is not a schema");
+    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 current;
+    return { document: identified.document, baseUri: identified.baseUri };
 }
 /**
- * Resolves `ref` against `root`, then keeps following `$ref` until it reaches
- * a schema that is not one. `visited` holds the pointers already entered on
- * THIS chain, so `a -> b -> a` throws instead of looping forever.
+ * 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 resolveRef(ref, root) {
+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.
@@ -71,24 +96,29 @@ function resolveRef(ref, root) {
         // 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`);
+            throw new ref_resolution_error_1.RefResolutionError(ref, `more than ${MAX_REF_HOPS} $ref hops`);
         }
-        if (!currentRef.startsWith("#")) {
-            throw new RefResolutionError(currentRef, "external references are not supported");
+        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(" -> ")}`);
         }
-        if (visited.has(currentRef)) {
-            throw new RefResolutionError(ref, `circular reference: ${[...visited, currentRef].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 };
         }
-        visited.add(currentRef);
-        const target = followPointer(currentRef, root);
-        if (!(0, draft07_types_1.isSchemaObject)(target) || target.$ref === undefined)
-            return target;
-        currentRef = target.$ref;
+        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 the document and without entering a
- * cycle. It answers the question without making the caller catch to find out.
+ * 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 {
@@ -96,7 +126,7 @@ function isResolvableRef(ref, root) {
         return true;
     }
     catch (error) {
-        if (error instanceof RefResolutionError)
+        if (error instanceof ref_resolution_error_1.RefResolutionError)
             return false;
         throw error;
     }

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

@@ -1,62 +1,88 @@
+import { RefResolutionError } from "./ref-resolution-error.mjs";
 import { isDraft07Schema, isSchemaObject } from "./draft07.types.mjs";
-import { isArray, isPlainObject } from "../types/index.mjs";
-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);
-    }
-}
+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;
-/** RFC 6901: `~1` is "/" and `~0` is "~", decoded in that order. */
-function decodePointerToken(token) {
-    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+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 };
 }
-function toPointerTokens(ref) {
-    const pointer = ref.slice(1);
-    if (pointer === "" || pointer === "/")
-        return [];
-    return pointer.split("/").slice(1).map(decodePointerToken);
+/** True for `#name`: a plain-name fragment, which names rather than locates. */
+function isPlainNameFragment(fragment) {
+    return fragment !== "" && !fragment.startsWith("/");
 }
 /**
- * `definitions` and `$defs` are the same container to a pointer: a Draft-07
- * document spells it one way, a 2019-09 document the other, and a schema that
- * mixes them (they exist) must still resolve. A real `definitions` member
- * always wins, so a property literally named "definitions" is unaffected.
+ * 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 stepInto(current, token) {
-    if (isArray(current))
-        return current[Number(token)];
-    if (!isPlainObject(current))
-        return undefined;
-    if (token === "definitions" || token === "$defs") {
-        return current["definitions"] ?? current["$defs"];
+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,
+            },
+        };
     }
-    return current[token];
+    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);
 }
-function followPointer(ref, root) {
-    let current = root;
-    for (const token of toPointerTokens(ref)) {
-        current = stepInto(current, token);
-        if (current === undefined) {
-            throw new RefResolutionError(ref, `no schema at segment "${token}"`);
-        }
+/**
+ * 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 };
     }
-    if (!isDraft07Schema(current)) {
-        throw new RefResolutionError(ref, "the target is not a schema");
+    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 current;
+    return { document: identified.document, baseUri: identified.baseUri };
 }
 /**
- * Resolves `ref` against `root`, then keeps following `$ref` until it reaches
- * a schema that is not one. `visited` holds the pointers already entered on
- * THIS chain, so `a -> b -> a` throws instead of looping forever.
+ * 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 resolveRef(ref, root) {
+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.
@@ -67,22 +93,27 @@ export function resolveRef(ref, root) {
         if (hop > MAX_REF_HOPS) {
             throw new RefResolutionError(ref, `more than ${MAX_REF_HOPS} $ref hops`);
         }
-        if (!currentRef.startsWith("#")) {
-            throw new RefResolutionError(currentRef, "external references are not supported");
+        const absolute = resolveUriReference(current.baseUri, currentRef);
+        if (visited.has(absolute)) {
+            throw new RefResolutionError(ref, `circular reference: ${[...visited, absolute].join(" -> ")}`);
         }
-        if (visited.has(currentRef)) {
-            throw new RefResolutionError(ref, `circular reference: ${[...visited, currentRef].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 };
         }
-        visited.add(currentRef);
-        const target = followPointer(currentRef, root);
-        if (!isSchemaObject(target) || target.$ref === undefined)
-            return target;
-        currentRef = target.$ref;
+        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 the document and without entering a
- * cycle. It answers the question without making the caller catch to find out.
+ * 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 {

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;