@maroonedog/luq 0.1.2-alpha → 2.1.0

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

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSchemaRegistry = createSchemaRegistry;
+// ===========================================================================
+// L8  src/json-schema/schema-registry.ts — どの URI がどのスキーマを指すか。
+//
+// Draft-07 §8.2 では `$id` が二つの働きをする: 場所を示す URI はベースを
+// 立て直し、`#name` の形は**位置に依らない名前**を付ける。どちらも
+// 「この URI はこのノード」という索引で、それがこのファイルの責務である。
+// ポインタ (`#/definitions/x`) を辿るのは場所の話なので resolve-ref.ts が持つ。
+//
+// 外部文書は**呼び出し側が渡したものだけ**である。Luq は取りに行かない:
+// 関数ではなく地図 (`externalDocuments`) を受けるのは、そうすれば
+//   * スキーマに書かれた URI でプロセスがソケットを開くことがない (SSRF)、
+//   * 変換が同期のままで、CSP でも動く、
+//   * 何が読まれうるかが呼び出し側のコードに全部書いてある、
+// の三つが同時に成り立つからで、非同期ローダーではどれも失われる。
+// ===========================================================================
+const draft07_types_1 = require("./draft07.types");
+const types_1 = require("../types");
+const uri_reference_1 = require("./uri-reference");
+/** Keywords whose value is ONE schema. */
+const SCHEMA_VALUED = Object.freeze([
+    "additionalProperties",
+    "additionalItems",
+    "contains",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+]);
+/** Keywords whose value is an ARRAY of schemas. `items` is in both lists. */
+const SCHEMA_LIST_VALUED = Object.freeze([
+    "allOf",
+    "anyOf",
+    "oneOf",
+]);
+/** Keywords whose value is a MAP of name to schema. */
+const SCHEMA_MAP_VALUED = Object.freeze([
+    "properties",
+    "patternProperties",
+    "definitions",
+    "$defs",
+    "dependencies",
+]);
+function walkSchema(schema, base, document, register) {
+    if (!(0, draft07_types_1.isSchemaObject)(schema))
+        return;
+    const id = typeof schema.$id === "string" ? schema.$id : undefined;
+    const here = (0, uri_reference_1.nextBaseUri)(base, id);
+    // A base-setting `$id` starts a new resource, so the node becomes the
+    // document every relative pointer under it resolves against.
+    const startsResource = id !== undefined && here !== base;
+    const inner = startsResource ? schema : document;
+    if (startsResource) {
+        register((0, uri_reference_1.normalizeUri)(here), { schema, baseUri: here, document: schema });
+    }
+    const anchor = (0, uri_reference_1.readAnchor)(id);
+    if (anchor !== undefined) {
+        register((0, uri_reference_1.normalizeUri)(`${here}#${anchor}`), {
+            schema,
+            baseUri: here,
+            document: inner,
+        });
+    }
+    walkMembers(schema, here, inner, register);
+}
+/**
+ * Read by ENTRY rather than by indexing the typed node: Draft07SchemaObject
+ * declares its keywords and carries no index signature, and reaching a keyword
+ * by name would need an assertion — src/core/type-erasure.ts is the only place
+ * permitted to write one, and this is not it.
+ */
+function walkMembers(schema, base, document, register) {
+    for (const [keyword, value] of Object.entries(schema)) {
+        if (keyword === "items") {
+            // The one keyword with both shapes, so it is walked as both.
+            walkIfSchema(value, base, document, register);
+            walkList(value, base, document, register);
+            continue;
+        }
+        if (SCHEMA_VALUED.includes(keyword)) {
+            walkIfSchema(value, base, document, register);
+        }
+        else if (SCHEMA_LIST_VALUED.includes(keyword)) {
+            walkList(value, base, document, register);
+        }
+        else if (SCHEMA_MAP_VALUED.includes(keyword)) {
+            walkMap(value, base, document, register);
+        }
+    }
+}
+function walkIfSchema(value, base, document, register) {
+    if (!(0, draft07_types_1.isDraft07Schema)(value))
+        return;
+    walkSchema(value, base, document, register);
+}
+function walkList(value, base, document, register) {
+    if (!(0, types_1.isArray)(value))
+        return;
+    for (const member of value)
+        walkIfSchema(member, base, document, register);
+}
+function walkMap(value, base, document, register) {
+    if (!(0, types_1.isPlainObject)(value))
+        return;
+    for (const member of Object.values(value)) {
+        walkIfSchema(member, base, document, register);
+    }
+}
+/**
+ * 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.
+ */
+function createSchemaRegistry(root, externalDocuments = {}) {
+    const byUri = new Map();
+    const register = (uri, target) => {
+        if (!byUri.has(uri))
+            byUri.set(uri, target);
+    };
+    for (const [uri, document] of Object.entries(externalDocuments)) {
+        if (!(0, draft07_types_1.isDraft07Schema)(document))
+            continue;
+        const key = (0, uri_reference_1.normalizeUri)(uri);
+        register(key, { schema: document, baseUri: key, document });
+    }
+    for (const [uri, document] of Object.entries(externalDocuments)) {
+        if (!(0, draft07_types_1.isDraft07Schema)(document))
+            continue;
+        walkSchema(document, (0, uri_reference_1.normalizeUri)(uri), document, register);
+    }
+    walkSchema(root, "", root, register);
+    return {
+        findIdentified: (uri) => byUri.get((0, uri_reference_1.normalizeUri)(uri)),
+    };
+}

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

@@ -0,0 +1,139 @@
+// ===========================================================================
+// L8  src/json-schema/schema-registry.ts — どの URI がどのスキーマを指すか。
+//
+// Draft-07 §8.2 では `$id` が二つの働きをする: 場所を示す URI はベースを
+// 立て直し、`#name` の形は**位置に依らない名前**を付ける。どちらも
+// 「この URI はこのノード」という索引で、それがこのファイルの責務である。
+// ポインタ (`#/definitions/x`) を辿るのは場所の話なので resolve-ref.ts が持つ。
+//
+// 外部文書は**呼び出し側が渡したものだけ**である。Luq は取りに行かない:
+// 関数ではなく地図 (`externalDocuments`) を受けるのは、そうすれば
+//   * スキーマに書かれた URI でプロセスがソケットを開くことがない (SSRF)、
+//   * 変換が同期のままで、CSP でも動く、
+//   * 何が読まれうるかが呼び出し側のコードに全部書いてある、
+// の三つが同時に成り立つからで、非同期ローダーではどれも失われる。
+// ===========================================================================
+import { isDraft07Schema, isSchemaObject } from "./draft07.types.mjs";
+import { isArray, isPlainObject } from "../types/index.mjs";
+import { nextBaseUri, normalizeUri, readAnchor } from "./uri-reference.mjs";
+/** Keywords whose value is ONE schema. */
+const SCHEMA_VALUED = Object.freeze([
+    "additionalProperties",
+    "additionalItems",
+    "contains",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+]);
+/** Keywords whose value is an ARRAY of schemas. `items` is in both lists. */
+const SCHEMA_LIST_VALUED = Object.freeze([
+    "allOf",
+    "anyOf",
+    "oneOf",
+]);
+/** Keywords whose value is a MAP of name to schema. */
+const SCHEMA_MAP_VALUED = Object.freeze([
+    "properties",
+    "patternProperties",
+    "definitions",
+    "$defs",
+    "dependencies",
+]);
+function walkSchema(schema, base, document, register) {
+    if (!isSchemaObject(schema))
+        return;
+    const id = typeof schema.$id === "string" ? schema.$id : undefined;
+    const here = nextBaseUri(base, id);
+    // A base-setting `$id` starts a new resource, so the node becomes the
+    // document every relative pointer under it resolves against.
+    const startsResource = id !== undefined && here !== base;
+    const inner = startsResource ? schema : document;
+    if (startsResource) {
+        register(normalizeUri(here), { schema, baseUri: here, document: schema });
+    }
+    const anchor = readAnchor(id);
+    if (anchor !== undefined) {
+        register(normalizeUri(`${here}#${anchor}`), {
+            schema,
+            baseUri: here,
+            document: inner,
+        });
+    }
+    walkMembers(schema, here, inner, register);
+}
+/**
+ * Read by ENTRY rather than by indexing the typed node: Draft07SchemaObject
+ * declares its keywords and carries no index signature, and reaching a keyword
+ * by name would need an assertion — src/core/type-erasure.ts is the only place
+ * permitted to write one, and this is not it.
+ */
+function walkMembers(schema, base, document, register) {
+    for (const [keyword, value] of Object.entries(schema)) {
+        if (keyword === "items") {
+            // The one keyword with both shapes, so it is walked as both.
+            walkIfSchema(value, base, document, register);
+            walkList(value, base, document, register);
+            continue;
+        }
+        if (SCHEMA_VALUED.includes(keyword)) {
+            walkIfSchema(value, base, document, register);
+        }
+        else if (SCHEMA_LIST_VALUED.includes(keyword)) {
+            walkList(value, base, document, register);
+        }
+        else if (SCHEMA_MAP_VALUED.includes(keyword)) {
+            walkMap(value, base, document, register);
+        }
+    }
+}
+function walkIfSchema(value, base, document, register) {
+    if (!isDraft07Schema(value))
+        return;
+    walkSchema(value, base, document, register);
+}
+function walkList(value, base, document, register) {
+    if (!isArray(value))
+        return;
+    for (const member of value)
+        walkIfSchema(member, base, document, register);
+}
+function walkMap(value, base, document, register) {
+    if (!isPlainObject(value))
+        return;
+    for (const member of Object.values(value)) {
+        walkIfSchema(member, base, document, register);
+    }
+}
+/**
+ * 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 function createSchemaRegistry(root, externalDocuments = {}) {
+    const byUri = new Map();
+    const register = (uri, target) => {
+        if (!byUri.has(uri))
+            byUri.set(uri, target);
+    };
+    for (const [uri, document] of Object.entries(externalDocuments)) {
+        if (!isDraft07Schema(document))
+            continue;
+        const key = normalizeUri(uri);
+        register(key, { schema: document, baseUri: key, document });
+    }
+    for (const [uri, document] of Object.entries(externalDocuments)) {
+        if (!isDraft07Schema(document))
+            continue;
+        walkSchema(document, normalizeUri(uri), document, register);
+    }
+    walkSchema(root, "", root, register);
+    return {
+        findIdentified: (uri) => byUri.get(normalizeUri(uri)),
+    };
+}

package/dist/json-schema/schema-to-declarations.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from "../plugin-kit/compiled-rule";
+import type { Draft07SchemaObject } from "./draft07.types";
+import type { ChildSchema, StructuralContext, StructuralExpansionTable, StructuralKeyword } from "./structural-expansion.types";
+export declare const STRUCTURAL_EXPANSIONS: StructuralExpansionTable;
+export declare function isStructuralKeyword(name: string): name is StructuralKeyword;
+/** Every child path a schema declares: `properties` keys and `items`' `[*]`. */
+export declare function readChildSchemas(schema: Draft07SchemaObject): readonly ChildSchema[];
+/** The rules a schema imposes ON ITS OWN SUBJECT, children excluded. */
+export declare function expandSchemaRules(schema: Draft07SchemaObject, context: StructuralContext): readonly Rule[];

package/dist/json-schema/schema-to-declarations.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRUCTURAL_EXPANSIONS = void 0;
+exports.isStructuralKeyword = isStructuralKeyword;
+exports.readChildSchemas = readChildSchemas;
+exports.expandSchemaRules = expandSchemaRules;
+const collect_definitions_1 = require("./collect-definitions");
+const compose_conditional_1 = require("./compose-conditional");
+const compose_keyword_1 = require("./compose-keyword");
+const declare_additional_properties_1 = require("./declare-additional-properties");
+const declare_object_keywords_1 = require("./declare-object-keywords");
+const declare_required_properties_1 = require("./declare-required-properties");
+const declare_scalar_keywords_1 = require("./declare-scalar-keywords");
+const declare_value_keywords_1 = require("./declare-value-keywords");
+const flatten_array_schema_1 = require("./flatten-array-schema");
+const keyword_map_1 = require("./keyword-map");
+const structural_expansion_types_1 = require("./structural-expansion.types");
+const unsupported_keyword_error_1 = require("./unsupported-keyword-error");
+const CONSUMED_BY_IF = "inert without `if` (Draft-07 §6.6.2); composed there";
+exports.STRUCTURAL_EXPANSIONS = {
+    $ref: {
+        expandsTo: "consumed",
+        consumedBy: "resolve-ref",
+        reason: "the node is replaced before any keyword is read",
+    },
+    definitions: {
+        expandsTo: "consumed",
+        consumedBy: "collect-definitions",
+        reason: "a container of schemas, never a constraint",
+    },
+    type: {
+        expandsTo: "rules",
+        toRules: (schema, context) => [
+            ...(0, declare_value_keywords_1.declareTypeRules)(schema, context),
+            ...(0, declare_value_keywords_1.declareIntegerRules)(schema, context),
+        ],
+    },
+    enum: { expandsTo: "rules", toRules: declare_value_keywords_1.declareEnumRules },
+    allOf: { expandsTo: "rules", toRules: compose_keyword_1.composeAllOf },
+    anyOf: { expandsTo: "rules", toRules: compose_keyword_1.composeAnyOf },
+    oneOf: { expandsTo: "rules", toRules: compose_keyword_1.composeOneOf },
+    not: { expandsTo: "rules", toRules: compose_keyword_1.composeNot },
+    if: { expandsTo: "rules", toRules: compose_conditional_1.composeConditional },
+    then: {
+        expandsTo: "consumed",
+        consumedBy: "compose-conditional",
+        reason: CONSUMED_BY_IF,
+    },
+    else: {
+        expandsTo: "consumed",
+        consumedBy: "compose-conditional",
+        reason: CONSUMED_BY_IF,
+    },
+    format: { expandsTo: "rules", toRules: declare_scalar_keywords_1.declareFormatRules },
+    items: {
+        expandsTo: "rules-and-declarations",
+        toRules: flatten_array_schema_1.composeTupleItems,
+        toChildren: flatten_array_schema_1.readItemChildren,
+    },
+    additionalItems: {
+        expandsTo: "consumed",
+        consumedBy: "flatten-array-schema",
+        reason: "the rest branch of the tuple form of `items`",
+    },
+    contains: { expandsTo: "rules", toRules: flatten_array_schema_1.composeContains },
+    properties: { expandsTo: "declarations", toChildren: declare_object_keywords_1.readPropertyChildren },
+    patternProperties: { expandsTo: "rules", toRules: declare_object_keywords_1.declarePatternProperties },
+    dependencies: { expandsTo: "rules", toRules: declare_object_keywords_1.declareDependencies },
+    propertyNames: { expandsTo: "rules", toRules: declare_object_keywords_1.declarePropertyNames },
+};
+function isStructuralKeyword(name) {
+    return Object.prototype.hasOwnProperty.call(exports.STRUCTURAL_EXPANSIONS, name);
+}
+/** Every child path a schema declares: `properties` keys and `items`' `[*]`. */
+function readChildSchemas(schema) {
+    const children = [];
+    for (const expansion of Object.values(exports.STRUCTURAL_EXPANSIONS)) {
+        const toChildren = (0, structural_expansion_types_1.readChildExpansion)(expansion);
+        if (toChildren === undefined)
+            continue;
+        children.push(...toChildren(schema));
+    }
+    return Object.freeze(children);
+}
+/**
+ * A name the table does not know is an ANNOTATION and is ignored (Draft-07
+ * §4.3.2). A name Luq recognises as belonging to another dialect is not: it
+ * would change the meaning of the document, so it is refused by name.
+ */
+function assertKeywordIsConvertible(keyword) {
+    if ((0, keyword_map_1.findKeywordHandling)(keyword) !== undefined)
+        return;
+    if ((0, collect_definitions_1.isDefinitionContainer)(keyword))
+        return;
+    const note = keyword_map_1.NON_DRAFT07_KEYWORDS[keyword];
+    if (note !== undefined)
+        throw new unsupported_keyword_error_1.UnsupportedKeywordError(keyword, note);
+}
+/** The rules a schema imposes ON ITS OWN SUBJECT, children excluded. */
+function expandSchemaRules(schema, context) {
+    const rules = [
+        ...(0, declare_scalar_keywords_1.declareStringRules)(schema, context),
+        ...(0, declare_scalar_keywords_1.declareNumberRules)(schema, context),
+        ...(0, flatten_array_schema_1.declareArrayRules)(schema, context),
+        ...(0, declare_object_keywords_1.declareObjectRules)(schema, context),
+        ...(0, declare_value_keywords_1.declareConstRules)(schema, context),
+        ...(0, declare_additional_properties_1.declareAdditionalPropertiesSchema)(schema, context),
+        ...(0, declare_required_properties_1.declareRequiredProperties)(schema, context),
+    ];
+    for (const keyword of Object.keys(schema)) {
+        assertKeywordIsConvertible(keyword);
+    }
+    // Driven by the TABLE, not by the keys somebody remembered to look at: every
+    // expansion self-gates on its own keyword, so a structural keyword can never
+    // be present in the document and unreached here.
+    for (const expansion of Object.values(exports.STRUCTURAL_EXPANSIONS)) {
+        const toRules = (0, structural_expansion_types_1.readRuleExpansion)(expansion);
+        if (toRules === undefined)
+            continue;
+        rules.push(...toRules(schema, context));
+    }
+    return Object.freeze(rules);
+}

package/dist/json-schema/schema-to-declarations.mjs

@@ -0,0 +1,117 @@
+import { isDefinitionContainer } from "./collect-definitions.mjs";
+import { composeConditional } from "./compose-conditional.mjs";
+import { composeAllOf, composeAnyOf, composeNot, composeOneOf, } from "./compose-keyword.mjs";
+import { declareAdditionalPropertiesSchema } from "./declare-additional-properties.mjs";
+import { declareDependencies, declareObjectRules, declarePatternProperties, declarePropertyNames, readPropertyChildren, } from "./declare-object-keywords.mjs";
+import { declareRequiredProperties } from "./declare-required-properties.mjs";
+import { declareFormatRules, declareNumberRules, declareStringRules, } from "./declare-scalar-keywords.mjs";
+import { declareConstRules, declareEnumRules, declareIntegerRules, declareTypeRules, } from "./declare-value-keywords.mjs";
+import { composeContains, composeTupleItems, declareArrayRules, readItemChildren, } from "./flatten-array-schema.mjs";
+import { NON_DRAFT07_KEYWORDS, findKeywordHandling } from "./keyword-map.mjs";
+import { readChildExpansion, readRuleExpansion, } from "./structural-expansion.types.mjs";
+import { UnsupportedKeywordError } from "./unsupported-keyword-error.mjs";
+const CONSUMED_BY_IF = "inert without `if` (Draft-07 §6.6.2); composed there";
+export const STRUCTURAL_EXPANSIONS = {
+    $ref: {
+        expandsTo: "consumed",
+        consumedBy: "resolve-ref",
+        reason: "the node is replaced before any keyword is read",
+    },
+    definitions: {
+        expandsTo: "consumed",
+        consumedBy: "collect-definitions",
+        reason: "a container of schemas, never a constraint",
+    },
+    type: {
+        expandsTo: "rules",
+        toRules: (schema, context) => [
+            ...declareTypeRules(schema, context),
+            ...declareIntegerRules(schema, context),
+        ],
+    },
+    enum: { expandsTo: "rules", toRules: declareEnumRules },
+    allOf: { expandsTo: "rules", toRules: composeAllOf },
+    anyOf: { expandsTo: "rules", toRules: composeAnyOf },
+    oneOf: { expandsTo: "rules", toRules: composeOneOf },
+    not: { expandsTo: "rules", toRules: composeNot },
+    if: { expandsTo: "rules", toRules: composeConditional },
+    then: {
+        expandsTo: "consumed",
+        consumedBy: "compose-conditional",
+        reason: CONSUMED_BY_IF,
+    },
+    else: {
+        expandsTo: "consumed",
+        consumedBy: "compose-conditional",
+        reason: CONSUMED_BY_IF,
+    },
+    format: { expandsTo: "rules", toRules: declareFormatRules },
+    items: {
+        expandsTo: "rules-and-declarations",
+        toRules: composeTupleItems,
+        toChildren: readItemChildren,
+    },
+    additionalItems: {
+        expandsTo: "consumed",
+        consumedBy: "flatten-array-schema",
+        reason: "the rest branch of the tuple form of `items`",
+    },
+    contains: { expandsTo: "rules", toRules: composeContains },
+    properties: { expandsTo: "declarations", toChildren: readPropertyChildren },
+    patternProperties: { expandsTo: "rules", toRules: declarePatternProperties },
+    dependencies: { expandsTo: "rules", toRules: declareDependencies },
+    propertyNames: { expandsTo: "rules", toRules: declarePropertyNames },
+};
+export function isStructuralKeyword(name) {
+    return Object.prototype.hasOwnProperty.call(STRUCTURAL_EXPANSIONS, name);
+}
+/** Every child path a schema declares: `properties` keys and `items`' `[*]`. */
+export function readChildSchemas(schema) {
+    const children = [];
+    for (const expansion of Object.values(STRUCTURAL_EXPANSIONS)) {
+        const toChildren = readChildExpansion(expansion);
+        if (toChildren === undefined)
+            continue;
+        children.push(...toChildren(schema));
+    }
+    return Object.freeze(children);
+}
+/**
+ * A name the table does not know is an ANNOTATION and is ignored (Draft-07
+ * §4.3.2). A name Luq recognises as belonging to another dialect is not: it
+ * would change the meaning of the document, so it is refused by name.
+ */
+function assertKeywordIsConvertible(keyword) {
+    if (findKeywordHandling(keyword) !== undefined)
+        return;
+    if (isDefinitionContainer(keyword))
+        return;
+    const note = NON_DRAFT07_KEYWORDS[keyword];
+    if (note !== undefined)
+        throw new UnsupportedKeywordError(keyword, note);
+}
+/** The rules a schema imposes ON ITS OWN SUBJECT, children excluded. */
+export function expandSchemaRules(schema, context) {
+    const rules = [
+        ...declareStringRules(schema, context),
+        ...declareNumberRules(schema, context),
+        ...declareArrayRules(schema, context),
+        ...declareObjectRules(schema, context),
+        ...declareConstRules(schema, context),
+        ...declareAdditionalPropertiesSchema(schema, context),
+        ...declareRequiredProperties(schema, context),
+    ];
+    for (const keyword of Object.keys(schema)) {
+        assertKeywordIsConvertible(keyword);
+    }
+    // Driven by the TABLE, not by the keys somebody remembered to look at: every
+    // expansion self-gates on its own keyword, so a structural keyword can never
+    // be present in the document and unreached here.
+    for (const expansion of Object.values(STRUCTURAL_EXPANSIONS)) {
+        const toRules = readRuleExpansion(expansion);
+        if (toRules === undefined)
+            continue;
+        rules.push(...toRules(schema, context));
+    }
+    return Object.freeze(rules);
+}

package/dist/json-schema/structural-expansion.types.d.ts

@@ -0,0 +1,90 @@
+import type { ChainBuildContext } from "../chain/create-chain-node";
+import type { CompositeBranch, Rule } from "../plugin-kit/compiled-rule";
+import type { RuleBuildContext } from "../plugin-kit/rule-build-context";
+import type { MessageContextExtra } from "../types";
+import type { Draft07Schema, Draft07SchemaObject } from "./draft07.types";
+import type { RefScope } from "./ref-scope";
+import type { JsonSchemaBag } from "./json-schema-bag.types";
+/**
+ * The nineteen keywords `draft07KeywordMap` marks `structural`. Written out by
+ * hand so the table below can be total over it; a runtime test in
+ * test/unit/json-schema/convert/ asserts this union has EXACTLY the members the
+ * keyword map marks structural, in both directions, so the two cannot drift.
+ */
+export type StructuralKeyword = "$ref" | "definitions" | "type" | "enum" | "allOf" | "anyOf" | "oneOf" | "not" | "if" | "then" | "else" | "format" | "items" | "additionalItems" | "contains" | "properties" | "patternProperties" | "dependencies" | "propertyNames";
+/**
+ * One step down from a schema to a sub-schema that gets its OWN declared path.
+ * `step` is already in the L1 path grammar: `.name` for a property, `[*]` for
+ * an array element, so joining is concatenation and never string surgery.
+ */
+export interface ChildSchema {
+    readonly step: string;
+    readonly schema: Draft07Schema;
+    readonly isRequired: boolean;
+}
+/**
+ * What an expansion may reach. `collectSubSchemaRules` and `toBranch` are
+ * INJECTED rather than imported: compose-keyword needs to convert its own
+ * sub-schemas, and schema-to-declarations needs compose-keyword, so importing
+ * either way round would close a cycle. schema-to-declarations is the single
+ * supplier of both.
+ */
+export interface StructuralContext {
+    readonly bag: JsonSchemaBag;
+    readonly build: ChainBuildContext;
+    /**
+     * WHERE this node is being read from. It replaces the bare `root` this
+     * interface used to carry: a `$ref` is a URI reference, so resolving one
+     * needs the base URI in force and the index of what a URI can name, and a
+     * root cannot express either. See ref-scope.ts.
+     */
+    readonly scope: RefScope;
+    /**
+     * The `$ref` pointers already entered on this branch of the conversion. A
+     * repeat is a RECURSIVE definition, whose expansion does not terminate, so
+     * the sub-schema converter stops there instead of building forever.
+     */
+    readonly visitedRefs: readonly string[];
+    /** Rules a SUB-schema imposes on the SAME subject (allOf arms, if/then). */
+    collectSubSchemaRules(schema: Draft07Schema): readonly Rule[];
+    /** A sub-schema as one composite branch: own rules plus relative fields. */
+    toBranch(label: string, schema: Draft07Schema): CompositeBranch;
+    /**
+     * What a bag plugin's `build()` needs. Written once here so no expansion
+     * assembles a RuleBuildContext of its own and drifts on severity or code.
+     */
+    ruleContextFor<C extends MessageContextExtra>(pluginName: string, code: string): RuleBuildContext<C>;
+}
+export type ExpandToRules = (schema: Draft07SchemaObject, context: StructuralContext) => readonly Rule[];
+export type ExpandToChildren = (schema: Draft07SchemaObject) => readonly ChildSchema[];
+/** The modules allowed to consume a keyword on another keyword's behalf. */
+export type StructuralConsumer = "resolve-ref" | "collect-definitions" | "compose-conditional" | "flatten-array-schema";
+interface RulesExpansion {
+    readonly expandsTo: "rules";
+    readonly toRules: ExpandToRules;
+}
+interface ChildrenExpansion {
+    readonly expandsTo: "declarations";
+    readonly toChildren: ExpandToChildren;
+}
+interface RulesAndChildrenExpansion {
+    readonly expandsTo: "rules-and-declarations";
+    readonly toRules: ExpandToRules;
+    readonly toChildren: ExpandToChildren;
+}
+/** The only entry with no function, and it must name its consumer. */
+interface ConsumedExpansion {
+    readonly expandsTo: "consumed";
+    readonly consumedBy: StructuralConsumer;
+    readonly reason: string;
+}
+export type StructuralExpansion = RulesExpansion | ChildrenExpansion | RulesAndChildrenExpansion | ConsumedExpansion;
+/** Total over the vocabulary: a forgotten recursion is a compile error. */
+export type StructuralExpansionTable = {
+    readonly [Keyword in StructuralKeyword]: StructuralExpansion;
+};
+/** Narrows an expansion to the ones that contribute rules at this path. */
+export declare function readRuleExpansion(expansion: StructuralExpansion): ExpandToRules | undefined;
+/** Narrows an expansion to the ones that contribute child declarations. */
+export declare function readChildExpansion(expansion: StructuralExpansion): ExpandToChildren | undefined;
+export {};

package/dist/json-schema/structural-expansion.types.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRuleExpansion = readRuleExpansion;
+exports.readChildExpansion = readChildExpansion;
+/** Narrows an expansion to the ones that contribute rules at this path. */
+function readRuleExpansion(expansion) {
+    if (expansion.expandsTo === "rules")
+        return expansion.toRules;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toRules;
+    }
+    return undefined;
+}
+/** Narrows an expansion to the ones that contribute child declarations. */
+function readChildExpansion(expansion) {
+    if (expansion.expandsTo === "declarations")
+        return expansion.toChildren;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toChildren;
+    }
+    return undefined;
+}

package/dist/json-schema/structural-expansion.types.mjs

@@ -0,0 +1,18 @@
+/** Narrows an expansion to the ones that contribute rules at this path. */
+export function readRuleExpansion(expansion) {
+    if (expansion.expandsTo === "rules")
+        return expansion.toRules;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toRules;
+    }
+    return undefined;
+}
+/** Narrows an expansion to the ones that contribute child declarations. */
+export function readChildExpansion(expansion) {
+    if (expansion.expandsTo === "declarations")
+        return expansion.toChildren;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toChildren;
+    }
+    return undefined;
+}

package/dist/json-schema/unsupported-keyword-error.d.ts

@@ -0,0 +1,5 @@
+export declare class UnsupportedKeywordError extends Error {
+    readonly keyword: string;
+    readonly reason: string;
+    constructor(keyword: string, reason: string);
+}