@maroonedog/luq 2.0.0 → 2.2.0

package/dist/json-schema/declare-object-keywords.mjs

@@ -15,9 +15,10 @@
 import { readChainRules } from "../chain/create-chain-node.mjs";
 import { createFieldSlots } from "../chain/create-field-slots.mjs";
 import { isStringArray } from "../types/index.mjs";
+import { applyAdditionalPropertiesBoolean } from "./declare-additional-properties.mjs";
 import { applyKeywordBinding } from "./apply-keyword-binding.mjs";
 import { toSchemaObject } from "./collect-definitions.mjs";
-import { additionalPropertiesBinding, maxPropertiesBinding, minPropertiesBinding, } from "./keyword-map-object.mjs";
+import { maxPropertiesBinding, minPropertiesBinding, } from "./keyword-map-object.mjs";
 const NO_RULES = Object.freeze([]);
 function readRules(chain) {
     return readChainRules(chain) ?? NO_RULES;
@@ -32,21 +33,14 @@ export function declareObjectRules(schema, context) {
     }
     const additional = schema.additionalProperties;
     if (typeof additional === "boolean") {
-        chain = applyKeywordBinding(chain, additionalPropertiesBinding, additional);
+        // §6.5.4 の対象は「properties にも patternProperties にも該当しない」キー。
+        // キーワード束縛は自分の値 (boolean) しか運べないので、パターンがある
+        // ときだけプラグインを直接呼ぶ。束縛のほうは残す: キーワード表と
+        // 「そのメソッドが実在する」というコンパイル時のゲートはそちらが持つ。
+        chain = applyAdditionalPropertiesBoolean(chain, schema, additional);
     }
     return readRules(chain);
 }
-/** The SCHEMA form of `additionalProperties`: every undeclared value obeys it. */
-export function declareAdditionalPropertiesSchema(schema, context) {
-    const additional = schema.additionalProperties;
-    if (additional === undefined || typeof additional === "boolean") {
-        return NO_RULES;
-    }
-    const plugin = context.bag.objectAdditionalPropertiesSchema;
-    return Object.freeze([
-        plugin.build(context.ruleContextFor(plugin.name, "additionalProperties"), context.collectSubSchemaRules(additional)),
-    ]);
-}
 /** EVERY matching pattern applies; 1.x broke after the first match. */
 export function declarePatternProperties(schema, context) {
     const patterns = schema.patternProperties;

package/dist/json-schema/declare-presence.d.ts

@@ -2,11 +2,17 @@ import type { Rule } from "../plugin-kit/compiled-rule";
 import type { IssueSeverity } from "../types";
 export interface PresenceDeclaration {
     readonly isRequired: boolean;
-    readonly allowsNull: boolean;
     readonly severity: IssueSeverity;
 }
 /**
- * A field that may be absent AND may be null needs no rule at all: that is
- * OPEN_PRESENCE, the policy a field with no presence rule already carries.
+ * The rule is emitted even when it forbids nothing, because it carries
+ * `nullIsValue` and that is not a permission — it is the statement that null
+ * has to be JUDGED here rather than settled by presence. A subject with no
+ * presence rule carries OPEN_PRESENCE, which ends the field on null before a
+ * single check runs; under Draft-07 that is wrong, because `false`,
+ * `{"not": {}}` and an `enum` without null all forbid null while saying
+ * nothing about `type`. Null therefore goes to the checks, and `type`
+ * (declare-value-keywords.ts) is what rejects it when the document says so —
+ * one answer instead of two that have to agree.
  */
 export declare function declarePresenceRules(declaration: PresenceDeclaration): readonly Rule[];

package/dist/json-schema/declare-presence.js

@@ -23,20 +23,26 @@ exports.declarePresenceRules = declarePresenceRules;
 // ===========================================================================
 const create_rule_1 = require("../plugin-kit/create-rule");
 /**
- * A field that may be absent AND may be null needs no rule at all: that is
- * OPEN_PRESENCE, the policy a field with no presence rule already carries.
+ * The rule is emitted even when it forbids nothing, because it carries
+ * `nullIsValue` and that is not a permission — it is the statement that null
+ * has to be JUDGED here rather than settled by presence. A subject with no
+ * presence rule carries OPEN_PRESENCE, which ends the field on null before a
+ * single check runs; under Draft-07 that is wrong, because `false`,
+ * `{"not": {}}` and an `enum` without null all forbid null while saying
+ * nothing about `type`. Null therefore goes to the checks, and `type`
+ * (declare-value-keywords.ts) is what rejects it when the document says so —
+ * one answer instead of two that have to agree.
  */
 function declarePresenceRules(declaration) {
-    if (!declaration.isRequired && declaration.allowsNull) {
-        return Object.freeze([]);
-    }
     return Object.freeze([
         (0, create_rule_1.presence)({
             code: declaration.isRequired ? "required" : "type",
             severity: declaration.severity,
             allowUndefined: !declaration.isRequired,
-            allowNull: declaration.allowsNull,
+            // Unreachable for null while nullIsValue is true; `type` decides.
+            allowNull: true,
             emptyStringIsMissing: false,
+            nullIsValue: true,
             describe: (messageContext) => declaration.isRequired
                 ? `${messageContext.path} is required`
                 : `${messageContext.path} must not be null`,

package/dist/json-schema/declare-presence.mjs

@@ -20,20 +20,26 @@
 // ===========================================================================
 import { presence } from "../plugin-kit/create-rule.mjs";
 /**
- * A field that may be absent AND may be null needs no rule at all: that is
- * OPEN_PRESENCE, the policy a field with no presence rule already carries.
+ * The rule is emitted even when it forbids nothing, because it carries
+ * `nullIsValue` and that is not a permission — it is the statement that null
+ * has to be JUDGED here rather than settled by presence. A subject with no
+ * presence rule carries OPEN_PRESENCE, which ends the field on null before a
+ * single check runs; under Draft-07 that is wrong, because `false`,
+ * `{"not": {}}` and an `enum` without null all forbid null while saying
+ * nothing about `type`. Null therefore goes to the checks, and `type`
+ * (declare-value-keywords.ts) is what rejects it when the document says so —
+ * one answer instead of two that have to agree.
  */
 export function declarePresenceRules(declaration) {
-    if (!declaration.isRequired && declaration.allowsNull) {
-        return Object.freeze([]);
-    }
     return Object.freeze([
         presence({
             code: declaration.isRequired ? "required" : "type",
             severity: declaration.severity,
             allowUndefined: !declaration.isRequired,
-            allowNull: declaration.allowsNull,
+            // Unreachable for null while nullIsValue is true; `type` decides.
+            allowNull: true,
             emptyStringIsMissing: false,
+            nullIsValue: true,
             describe: (messageContext) => declaration.isRequired
                 ? `${messageContext.path} is required`
                 : `${messageContext.path} must not be null`,

package/dist/json-schema/extensions/json-schema/index.d.ts

@@ -1,3 +1,4 @@
 export { SCHEMA_BRANCH_LABEL, collectDocumentRules, jsonSchemaPlugin, } from "./json-schema";
+export type { JsonSchemaOptions } from "./json-schema";
 export { NotASchemaError, UnsupportedKeywordError, RefResolutionError, buildFieldEntries, buildFromSchema, fromJsonSchema, isDraft07Schema, listBoundPluginNames, listDraft07Keywords, listFormatNames, } from "../../index";
 export type { Draft07Schema, Draft07SchemaObject, JsonSchemaBag, } from "../../index";

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

@@ -5,14 +5,29 @@ import type { Unchanged } from "../../../plugin-kit/marker.types";
 import { type JsonSchemaBag } from "../../index";
 /** The label the whole document carries inside the composite it becomes. */
 export declare const SCHEMA_BRANCH_LABEL = "schema";
+/**
+ * What the converter may reach beyond the document itself.
+ *
+ * `externalDocuments` is a MAP, deliberately, and not a loader function:
+ *   * Luq never opens a socket, so a schema cannot make the process fetch a
+ *     URL it names (SSRF) — what can be read is written in the caller's code;
+ *   * conversion stays synchronous, so `build()` keeps returning a validator
+ *     rather than a promise;
+ *   * nothing is evaluated, so the CSP guarantee is untouched.
+ * The caller fetches, reads from disk, or bundles — whichever is right for
+ * their deployment — and hands over what they already have.
+ */
+export interface JsonSchemaOptions {
+    readonly externalDocuments?: Readonly<Record<string, unknown>> | undefined;
+}
 /**
  * The document as a rule list over ONE subject. Exported because it is the
  * only part of this plugin the full-feature bundle needs, and because a test
  * can then count the rules a document produces without building a validator.
  */
-export declare function collectDocumentRules(ctx: RuleBuildContext<MessageContextExtra>, document: unknown, bag: JsonSchemaBag): readonly Rule[];
+export declare function collectDocumentRules(ctx: RuleBuildContext<MessageContextExtra>, document: unknown, bag: JsonSchemaBag, options?: JsonSchemaOptions): readonly Rule[];
 export declare const jsonSchemaPlugin: import("../../../plugin-kit/plugin-definition").PluginDefinition<"jsonSchema", "jsonSchema", readonly TypeName[], {
-    args: readonly [document: unknown, bag: JsonSchemaBag];
+    args: readonly [document: unknown, bag: JsonSchemaBag, options?: JsonSchemaOptions];
     out: Unchanged;
     context: MessageContextExtra;
 }>;

package/dist/json-schema/extensions/json-schema/json-schema.js

@@ -57,41 +57,49 @@ const SCHEMA_SLOTS = [
 ];
 /** The label the whole document carries inside the composite it becomes. */
 exports.SCHEMA_BRANCH_LABEL = "schema";
+const NO_EXTERNAL_DOCUMENTS = Object.freeze({});
 /**
  * The document as a rule list over ONE subject. Exported because it is the
  * only part of this plugin the full-feature bundle needs, and because a test
  * can then count the rules a document produces without building a validator.
  */
-function collectDocumentRules(ctx, document, bag) {
+function collectDocumentRules(ctx, document, bag, options = {}) {
     if (!(0, index_1.isDraft07Schema)(document))
         throw new index_1.NotASchemaError(document);
     const root = document;
+    const scope = (0, index_1.createDocumentScope)(root, options.externalDocuments ?? NO_EXTERNAL_DOCUMENTS);
     // The seed's `chain` is a ChainBuildContext, whose three members a
     // RuleBuildContext already carries. Written inline because naming the type
     // would mean importing src/chain, which tier `extension` forbids.
     const seed = {
         bag,
-        root,
+        scope,
         chain: {
             fieldPath: ctx.fieldPath,
             declaredSiblingKeys: ctx.declaredSiblingKeys,
             config: ctx.config,
         },
     };
-    const node = (0, index_1.resolveSchemaNode)(root, root);
-    const context = (0, index_1.createStructuralContext)(seed, node, []);
-    return (0, index_1.collectSubSchemaRules)(root, context);
+    const resolved = (0, index_1.resolveSchemaNodeInScope)(root, scope);
+    const context = (0, index_1.createStructuralContext)(seed, resolved.node, [], resolved.scope);
+    // The branch subject carries its own null policy, like every sub-schema
+    // subject: collectSubSchemaRules puts it there. `judgesNull` on the plugin
+    // gets null as far as this composite; that policy gets it the rest of the
+    // way, into the document's own rules.
+    return (0, index_1.collectSubSchemaRules)(resolved.node, context);
 }
 exports.jsonSchemaPlugin = (0, plugin_definition_1.definePlugin)()({
     name: "jsonSchema",
+    // The document decides whether null is allowed, so null has to reach it.
+    judgesNull: true,
     method: "jsonSchema",
     slots: SCHEMA_SLOTS,
-    build: (ctx, document, bag) => (0, create_rule_1.composite)({
+    build: (ctx, document, bag, options) => (0, create_rule_1.composite)({
         code: ctx.code,
         messageFactory: ctx.messageFactory,
         severity: ctx.severity,
         branches: [
-            (0, create_rule_1.branch)(exports.SCHEMA_BRANCH_LABEL, collectDocumentRules(ctx, document, bag)),
+            (0, create_rule_1.branch)(exports.SCHEMA_BRANCH_LABEL, collectDocumentRules(ctx, document, bag, options)),
         ],
         combine: (runners) => (value, runContext) => runners[0]?.run(value, runContext) ?? types_1.PASS,
         describe: () => "Value does not match the JSON Schema document",

package/dist/json-schema/extensions/json-schema/json-schema.mjs

@@ -38,7 +38,7 @@
 import { branch, composite } from "../../../plugin-kit/create-rule.mjs";
 import { definePlugin } from "../../../plugin-kit/plugin-definition.mjs";
 import { PASS } from "../../../types/index.mjs";
-import { NotASchemaError, collectSubSchemaRules, createStructuralContext, isDraft07Schema, resolveSchemaNode, } from "../../index.mjs";
+import { NotASchemaError, collectSubSchemaRules, createStructuralContext, createDocumentScope, isDraft07Schema, resolveSchemaNodeInScope, } from "../../index.mjs";
 /** Every slot: a JSON Schema document constrains a value of any shape. */
 const SCHEMA_SLOTS = [
     "string",
@@ -53,41 +53,49 @@ const SCHEMA_SLOTS = [
 ];
 /** The label the whole document carries inside the composite it becomes. */
 export const SCHEMA_BRANCH_LABEL = "schema";
+const NO_EXTERNAL_DOCUMENTS = Object.freeze({});
 /**
  * The document as a rule list over ONE subject. Exported because it is the
  * only part of this plugin the full-feature bundle needs, and because a test
  * can then count the rules a document produces without building a validator.
  */
-export function collectDocumentRules(ctx, document, bag) {
+export function collectDocumentRules(ctx, document, bag, options = {}) {
     if (!isDraft07Schema(document))
         throw new NotASchemaError(document);
     const root = document;
+    const scope = createDocumentScope(root, options.externalDocuments ?? NO_EXTERNAL_DOCUMENTS);
     // The seed's `chain` is a ChainBuildContext, whose three members a
     // RuleBuildContext already carries. Written inline because naming the type
     // would mean importing src/chain, which tier `extension` forbids.
     const seed = {
         bag,
-        root,
+        scope,
         chain: {
             fieldPath: ctx.fieldPath,
             declaredSiblingKeys: ctx.declaredSiblingKeys,
             config: ctx.config,
         },
     };
-    const node = resolveSchemaNode(root, root);
-    const context = createStructuralContext(seed, node, []);
-    return collectSubSchemaRules(root, context);
+    const resolved = resolveSchemaNodeInScope(root, scope);
+    const context = createStructuralContext(seed, resolved.node, [], resolved.scope);
+    // The branch subject carries its own null policy, like every sub-schema
+    // subject: collectSubSchemaRules puts it there. `judgesNull` on the plugin
+    // gets null as far as this composite; that policy gets it the rest of the
+    // way, into the document's own rules.
+    return collectSubSchemaRules(resolved.node, context);
 }
 export const jsonSchemaPlugin = /*#__PURE__*/ definePlugin()({
     name: "jsonSchema",
+    // The document decides whether null is allowed, so null has to reach it.
+    judgesNull: true,
     method: "jsonSchema",
     slots: SCHEMA_SLOTS,
-    build: (ctx, document, bag) => composite({
+    build: (ctx, document, bag, options) => composite({
         code: ctx.code,
         messageFactory: ctx.messageFactory,
         severity: ctx.severity,
         branches: [
-            branch(SCHEMA_BRANCH_LABEL, collectDocumentRules(ctx, document, bag)),
+            branch(SCHEMA_BRANCH_LABEL, collectDocumentRules(ctx, document, bag, options)),
         ],
         combine: (runners) => (value, runContext) => runners[0]?.run(value, runContext) ?? PASS,
         describe: () => "Value does not match the JSON Schema document",

package/dist/json-schema/extensions/json-schema-full-feature/index.d.ts

@@ -1,4 +1,5 @@
 export { fromJsonSchema, jsonSchemaFullFeaturePlugin, } from "./json-schema-full-feature";
 export { jsonSchemaBag } from "./bundled-plugins";
 export { UNBOUND_BUNDLED_PLUGIN_NAMES, findStaleUnboundDeclarations, findUnbundledBoundPlugins, findUnexplainedBundledPlugins, listBundledPluginNames, } from "./bundle-coverage";
+export type { JsonSchemaOptions } from "../json-schema";
 export type { JsonSchemaBag } from "../../index";

package/dist/json-schema/extensions/json-schema-full-feature/json-schema-full-feature.d.ts

@@ -1,8 +1,9 @@
 import type { MessageContextExtra, TypeName } from "../../../types";
 import type { Unchanged } from "../../../plugin-kit/marker.types";
+import type { JsonSchemaOptions } from "../json-schema";
 import type { GlobalConfig } from "../../../types/global-config";
 export declare const jsonSchemaFullFeaturePlugin: import("../../../plugin-kit/plugin-definition").PluginDefinition<"jsonSchemaFullFeature", "jsonSchemaFullFeature", readonly TypeName[], {
-    args: readonly [document: unknown];
+    args: readonly [document: unknown, options?: JsonSchemaOptions];
     out: Unchanged;
     context: MessageContextExtra;
 }>;

package/dist/json-schema/extensions/json-schema-full-feature/json-schema-full-feature.js

@@ -41,9 +41,11 @@ const SCHEMA_SLOTS = [
 ];
 exports.jsonSchemaFullFeaturePlugin = (0, plugin_definition_1.definePlugin)()({
     name: "jsonSchemaFullFeature",
+    // The document decides whether null is allowed, so null has to reach it.
+    judgesNull: true,
     method: "jsonSchemaFullFeature",
     slots: SCHEMA_SLOTS,
-    build: (ctx, document) => json_schema_1.jsonSchemaPlugin.build(ctx, document, bundled_plugins_1.jsonSchemaBag),
+    build: (ctx, document, options) => json_schema_1.jsonSchemaPlugin.build(ctx, document, bundled_plugins_1.jsonSchemaBag, options),
 });
 /**
  * The documented one-import route:

package/dist/json-schema/extensions/json-schema-full-feature/json-schema-full-feature.mjs

@@ -37,9 +37,11 @@ const SCHEMA_SLOTS = [
 ];
 export const jsonSchemaFullFeaturePlugin = /*#__PURE__*/ definePlugin()({
     name: "jsonSchemaFullFeature",
+    // The document decides whether null is allowed, so null has to reach it.
+    judgesNull: true,
     method: "jsonSchemaFullFeature",
     slots: SCHEMA_SLOTS,
-    build: (ctx, document) => jsonSchemaPlugin.build(ctx, document, jsonSchemaBag),
+    build: (ctx, document, options) => jsonSchemaPlugin.build(ctx, document, jsonSchemaBag, options),
 });
 /**
  * The documented one-import route:

package/dist/json-schema/flatten-schema.js

@@ -91,7 +91,7 @@ function hasRootRuleKeyword(node) {
 /** The root node MINUS the three keywords the flattener applies itself. A rest
  *  destructuring, so the compiler and not a comment keeps the result a schema. */
 function dropDistributedKeywords(node) {
-    const { type, required, allOf, ...residual } = node;
+    const { type: _type, required: _required, allOf: _allOf, ...residual } = node;
     return residual;
 }
 /** Children of the root, merged across the `allOf` arms, first arm winning. */

package/dist/json-schema/flatten-schema.mjs

@@ -86,7 +86,7 @@ function hasRootRuleKeyword(node) {
 /** The root node MINUS the three keywords the flattener applies itself. A rest
  *  destructuring, so the compiler and not a comment keeps the result a schema. */
 function dropDistributedKeywords(node) {
-    const { type, required, allOf, ...residual } = node;
+    const { type: _type, required: _required, allOf: _allOf, ...residual } = node;
     return residual;
 }
 /** Children of the root, merged across the `allOf` arms, first arm winning. */

package/dist/json-schema/follow-json-pointer.d.ts

@@ -0,0 +1,23 @@
+/** `fragment` is what came AFTER the "#", so there is no prefix to strip. */
+export declare function toPointerTokens(fragment: string): readonly string[];
+/**
+ * `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.
+ */
+export declare function stepInto(current: unknown, token: string): unknown;
+/**
+ * ポインタを辿りながら、**途中で跨いだ `$id` を数える**。
+ *
+ * `#/definitions/baz/definitions/bar` の `baz` が `$id: "folder/"` を持つとき、
+ * `bar` の中に書かれた相対 `$ref` は folder/ の下で解決されなければならない。
+ * 着地したノードの `$id` だけを見ると、通過したノードの分が落ちる。
+ *
+ * ベースをどう進めるかは呼び出し側が渡す (`advance`)。この関数は「どのノードを
+ * どの順に跨いだか」だけを知っていればよく、URI の演算は持たない。
+ */
+export declare function walkPointer<TScope>(fragment: string, document: unknown, scope: TScope, advance: (scope: TScope, node: unknown) => TScope, onMissing: (token: string) => never): {
+    readonly node: unknown;
+    readonly scope: TScope;
+};

package/dist/json-schema/follow-json-pointer.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPointerTokens = toPointerTokens;
+exports.stepInto = stepInto;
+exports.walkPointer = walkPointer;
+// ===========================================================================
+// L8  src/json-schema/follow-json-pointer.ts — RFC 6901 のポインタを辿る。
+//
+// `$ref` のうち **場所** を表す部分だけを担う。どの文書を見るかは
+// schema-registry.ts と resolve-ref.ts の仕事で、ここは「その文書の中の
+// どこか」だけを答える。分けてあるのは、`$id` によるベース URI の話と
+// ポインタの復号の話が別物であり、混ぜると 200 行を超えて両方読みにくく
+// なるからである。
+// ===========================================================================
+const types_1 = require("../types");
+/** RFC 6901: `~1` is "/" and `~0` is "~", decoded in that order. */
+function decodePointerToken(token) {
+    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/**
+ * `$ref` は URI で、ポインタはそのフラグメント。RFC 6901 §6 は
+ * 「フラグメントの規則でパーセント符号化されている」と定めるので、
+ * **スラッシュで割る前にフラグメント全体を復号する**。
+ *
+ * 順序が意味を持つ。`#/definitions/percent%25field` は復号して
+ * `/definitions/percent%field` になり、そこで割ってトークンを得る。
+ * 先に割ってからトークンごとに復号すると `%25` は復号されるが、
+ * `%2F` が「区切りとしてのスラッシュ」に戻る仕様どおりの挙動にならない。
+ *
+ * 壊れたパーセント列 (`%zz`) は decodeURIComponent が投げるので、
+ * 復号できないポインタはそのまま扱う。ここで投げると、ポインタが1つ
+ * 壊れているだけで文書全体が読めなくなる。
+ */
+function decodeFragment(pointer) {
+    try {
+        return decodeURIComponent(pointer);
+    }
+    catch {
+        return pointer;
+    }
+}
+/** `fragment` is what came AFTER the "#", so there is no prefix to strip. */
+function toPointerTokens(fragment) {
+    const pointer = decodeFragment(fragment);
+    if (pointer === "")
+        return [];
+    // "/" は「ルート直下の空文字キー」であって空のトークン列ではない。
+    // ここを [] にすると `{"": ...}` を指すポインタがルートに化ける。
+    return pointer.split("/").slice(1).map(decodePointerToken);
+}
+/**
+ * `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.
+ */
+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"];
+    }
+    return current[token];
+}
+/**
+ * ポインタを辿りながら、**途中で跨いだ `$id` を数える**。
+ *
+ * `#/definitions/baz/definitions/bar` の `baz` が `$id: "folder/"` を持つとき、
+ * `bar` の中に書かれた相対 `$ref` は folder/ の下で解決されなければならない。
+ * 着地したノードの `$id` だけを見ると、通過したノードの分が落ちる。
+ *
+ * ベースをどう進めるかは呼び出し側が渡す (`advance`)。この関数は「どのノードを
+ * どの順に跨いだか」だけを知っていればよく、URI の演算は持たない。
+ */
+function walkPointer(fragment, document, scope, advance, onMissing) {
+    let current = document;
+    let here = scope;
+    for (const token of toPointerTokens(fragment)) {
+        current = stepInto(current, token);
+        if (current === undefined)
+            onMissing(token);
+        here = advance(here, current);
+    }
+    return { node: current, scope: here };
+}

package/dist/json-schema/follow-json-pointer.mjs

@@ -0,0 +1,82 @@
+// ===========================================================================
+// L8  src/json-schema/follow-json-pointer.ts — RFC 6901 のポインタを辿る。
+//
+// `$ref` のうち **場所** を表す部分だけを担う。どの文書を見るかは
+// schema-registry.ts と resolve-ref.ts の仕事で、ここは「その文書の中の
+// どこか」だけを答える。分けてあるのは、`$id` によるベース URI の話と
+// ポインタの復号の話が別物であり、混ぜると 200 行を超えて両方読みにくく
+// なるからである。
+// ===========================================================================
+import { isArray, isPlainObject } from "../types/index.mjs";
+/** RFC 6901: `~1` is "/" and `~0` is "~", decoded in that order. */
+function decodePointerToken(token) {
+    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/**
+ * `$ref` は URI で、ポインタはそのフラグメント。RFC 6901 §6 は
+ * 「フラグメントの規則でパーセント符号化されている」と定めるので、
+ * **スラッシュで割る前にフラグメント全体を復号する**。
+ *
+ * 順序が意味を持つ。`#/definitions/percent%25field` は復号して
+ * `/definitions/percent%field` になり、そこで割ってトークンを得る。
+ * 先に割ってからトークンごとに復号すると `%25` は復号されるが、
+ * `%2F` が「区切りとしてのスラッシュ」に戻る仕様どおりの挙動にならない。
+ *
+ * 壊れたパーセント列 (`%zz`) は decodeURIComponent が投げるので、
+ * 復号できないポインタはそのまま扱う。ここで投げると、ポインタが1つ
+ * 壊れているだけで文書全体が読めなくなる。
+ */
+function decodeFragment(pointer) {
+    try {
+        return decodeURIComponent(pointer);
+    }
+    catch {
+        return pointer;
+    }
+}
+/** `fragment` is what came AFTER the "#", so there is no prefix to strip. */
+export function toPointerTokens(fragment) {
+    const pointer = decodeFragment(fragment);
+    if (pointer === "")
+        return [];
+    // "/" は「ルート直下の空文字キー」であって空のトークン列ではない。
+    // ここを [] にすると `{"": ...}` を指すポインタがルートに化ける。
+    return pointer.split("/").slice(1).map(decodePointerToken);
+}
+/**
+ * `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.
+ */
+export 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"];
+    }
+    return current[token];
+}
+/**
+ * ポインタを辿りながら、**途中で跨いだ `$id` を数える**。
+ *
+ * `#/definitions/baz/definitions/bar` の `baz` が `$id: "folder/"` を持つとき、
+ * `bar` の中に書かれた相対 `$ref` は folder/ の下で解決されなければならない。
+ * 着地したノードの `$id` だけを見ると、通過したノードの分が落ちる。
+ *
+ * ベースをどう進めるかは呼び出し側が渡す (`advance`)。この関数は「どのノードを
+ * どの順に跨いだか」だけを知っていればよく、URI の演算は持たない。
+ */
+export function walkPointer(fragment, document, scope, advance, onMissing) {
+    let current = document;
+    let here = scope;
+    for (const token of toPointerTokens(fragment)) {
+        current = stepInto(current, token);
+        if (current === undefined)
+            onMissing(token);
+        here = advance(here, current);
+    }
+    return { node: current, scope: here };
+}

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

@@ -1,5 +1,5 @@
 export { NotASchemaError, buildFieldEntries, buildFromSchema, fromJsonSchema, } from "./build-from-schema";
-export { DEFINITION_CONTAINERS, collectDefinitionNames, isDefinitionContainer, readRefPointer, resolveSchemaNode, toSchemaObject, } from "./collect-definitions";
+export { DEFINITION_CONTAINERS, collectDefinitionNames, isDefinitionContainer, readRefPointer, resolveSchemaNode, resolveSchemaNodeInScope, toSchemaObject, } from "./collect-definitions";
 export { flattenSchema, joinDeclaredPath } from "./flatten-schema";
 export type { ReadChildSchemas, SchemaFieldDeclaration, } from "./flatten-schema";
 export { STRUCTURAL_EXPANSIONS, expandSchemaRules, isStructuralKeyword, readChildSchemas, } from "./schema-to-declarations";
@@ -10,7 +10,12 @@ export { declarePresenceRules } from "./declare-presence";
 export type { PresenceDeclaration } from "./declare-presence";
 export type { ConversionSeed } from "./create-structural-context";
 export type { ChildSchema, StructuralConsumer, StructuralContext, StructuralExpansion, StructuralExpansionTable, StructuralKeyword, } from "./structural-expansion.types";
-export { RefResolutionError, isResolvableRef, resolveRef } from "./resolve-ref";
+export { RefResolutionError } from "./ref-resolution-error";
+export { isResolvableRef, resolveRef, resolveRefInScope } from "./resolve-ref";
+export type { RefScope } from "./ref-scope";
+export { createDocumentScope, createLocalScope } from "./ref-scope";
+export type { SchemaRegistry } from "./schema-registry";
+export { createSchemaRegistry } from "./schema-registry";
 export { UnsupportedKeywordError } from "./unsupported-keyword-error";
 export { isDraft07Schema, isSchemaObject } from "./draft07.types";
 export type { Draft07Schema, Draft07SchemaObject, Draft07TypeKeyword, } from "./draft07.types";

package/dist/json-schema/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listFormatNames = exports.findFormatHandling = exports.listDraft07Keywords = exports.listBoundPluginNames = exports.isDraft07Keyword = exports.findKeywordHandling = exports.countKeywordHandlings = exports.assertKeywordSupported = exports.isSchemaObject = exports.isDraft07Schema = exports.UnsupportedKeywordError = exports.resolveRef = exports.isResolvableRef = exports.RefResolutionError = exports.declarePresenceRules = exports.declareRequiredProperties = exports.createStructuralContext = exports.toSchemaBranch = exports.collectSubSchemaRules = exports.readChildSchemas = exports.isStructuralKeyword = exports.expandSchemaRules = exports.STRUCTURAL_EXPANSIONS = exports.joinDeclaredPath = exports.flattenSchema = exports.toSchemaObject = exports.resolveSchemaNode = exports.readRefPointer = exports.isDefinitionContainer = exports.collectDefinitionNames = exports.DEFINITION_CONTAINERS = exports.fromJsonSchema = exports.buildFromSchema = exports.buildFieldEntries = exports.NotASchemaError = void 0;
+exports.listFormatNames = exports.findFormatHandling = exports.listDraft07Keywords = exports.listBoundPluginNames = exports.isDraft07Keyword = exports.findKeywordHandling = exports.countKeywordHandlings = exports.assertKeywordSupported = exports.isSchemaObject = exports.isDraft07Schema = exports.UnsupportedKeywordError = exports.createSchemaRegistry = exports.createLocalScope = exports.createDocumentScope = exports.resolveRefInScope = exports.resolveRef = exports.isResolvableRef = exports.RefResolutionError = exports.declarePresenceRules = exports.declareRequiredProperties = exports.createStructuralContext = exports.toSchemaBranch = exports.collectSubSchemaRules = exports.readChildSchemas = exports.isStructuralKeyword = exports.expandSchemaRules = exports.STRUCTURAL_EXPANSIONS = exports.joinDeclaredPath = exports.flattenSchema = exports.toSchemaObject = exports.resolveSchemaNodeInScope = exports.resolveSchemaNode = exports.readRefPointer = exports.isDefinitionContainer = exports.collectDefinitionNames = exports.DEFINITION_CONTAINERS = exports.fromJsonSchema = exports.buildFromSchema = exports.buildFieldEntries = exports.NotASchemaError = void 0;
 // ===========================================================================
 // L8  src/json-schema/index.ts — re-exports only. Nothing is defined here.
 //
@@ -18,6 +18,7 @@ Object.defineProperty(exports, "collectDefinitionNames", { enumerable: true, get
 Object.defineProperty(exports, "isDefinitionContainer", { enumerable: true, get: function () { return collect_definitions_1.isDefinitionContainer; } });
 Object.defineProperty(exports, "readRefPointer", { enumerable: true, get: function () { return collect_definitions_1.readRefPointer; } });
 Object.defineProperty(exports, "resolveSchemaNode", { enumerable: true, get: function () { return collect_definitions_1.resolveSchemaNode; } });
+Object.defineProperty(exports, "resolveSchemaNodeInScope", { enumerable: true, get: function () { return collect_definitions_1.resolveSchemaNodeInScope; } });
 Object.defineProperty(exports, "toSchemaObject", { enumerable: true, get: function () { return collect_definitions_1.toSchemaObject; } });
 var flatten_schema_1 = require("./flatten-schema");
 Object.defineProperty(exports, "flattenSchema", { enumerable: true, get: function () { return flatten_schema_1.flattenSchema; } });
@@ -36,10 +37,17 @@ var declare_required_properties_1 = require("./declare-required-properties");
 Object.defineProperty(exports, "declareRequiredProperties", { enumerable: true, get: function () { return declare_required_properties_1.declareRequiredProperties; } });
 var declare_presence_1 = require("./declare-presence");
 Object.defineProperty(exports, "declarePresenceRules", { enumerable: true, get: function () { return declare_presence_1.declarePresenceRules; } });
+var ref_resolution_error_1 = require("./ref-resolution-error");
+Object.defineProperty(exports, "RefResolutionError", { enumerable: true, get: function () { return ref_resolution_error_1.RefResolutionError; } });
 var resolve_ref_1 = require("./resolve-ref");
-Object.defineProperty(exports, "RefResolutionError", { enumerable: true, get: function () { return resolve_ref_1.RefResolutionError; } });
 Object.defineProperty(exports, "isResolvableRef", { enumerable: true, get: function () { return resolve_ref_1.isResolvableRef; } });
 Object.defineProperty(exports, "resolveRef", { enumerable: true, get: function () { return resolve_ref_1.resolveRef; } });
+Object.defineProperty(exports, "resolveRefInScope", { enumerable: true, get: function () { return resolve_ref_1.resolveRefInScope; } });
+var ref_scope_1 = require("./ref-scope");
+Object.defineProperty(exports, "createDocumentScope", { enumerable: true, get: function () { return ref_scope_1.createDocumentScope; } });
+Object.defineProperty(exports, "createLocalScope", { enumerable: true, get: function () { return ref_scope_1.createLocalScope; } });
+var schema_registry_1 = require("./schema-registry");
+Object.defineProperty(exports, "createSchemaRegistry", { enumerable: true, get: function () { return schema_registry_1.createSchemaRegistry; } });
 var unsupported_keyword_error_1 = require("./unsupported-keyword-error");
 Object.defineProperty(exports, "UnsupportedKeywordError", { enumerable: true, get: function () { return unsupported_keyword_error_1.UnsupportedKeywordError; } });
 var draft07_types_1 = require("./draft07.types");