@maroonedog/luq 0.1.2-alpha → 2.1.0

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

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EACH_STEP = void 0;
+exports.readItemChildren = readItemChildren;
+exports.composeTupleItems = composeTupleItems;
+exports.composeContains = composeContains;
+exports.declareArrayRules = declareArrayRules;
+// ===========================================================================
+// L8  src/json-schema/flatten-array-schema.ts — `items`, `additionalItems`,
+// `contains`.
+//
+// TWO SHAPES, ONE KEYWORD. `items` is either a schema (every element) or an
+// ARRAY of schemas (position i constrains element i). 1.x read only the first
+// shape and guessed the method name `tupleBuilder` for the second, which is not
+// a chain method, so the tuple form silently constrained nothing.
+//
+//   single form  ->  a CHILD DECLARATION at `path[*]`. That is better than
+//                    `.each()` here: the element gets a real declared path, so
+//                    its own `properties` become `path[*].name` and an issue
+//                    renders as `tags[2].name` rather than as a nested cause.
+//   tuple form   ->  ONE composite, built from create-rule.
+//
+// WHY NOT tupleBuilder (measured, not assumed): tupleBuilderPlugin rejects a
+// NON-ARRAY and enforces a LENGTH — exactly `value.length !== positions.length`
+// without a rest chain, and `value.length < positions.length` with one. Draft-07
+// §6.4 / §9.3.1 does neither: a non-array is not an array constraint's business
+// at all, a SHORT array is valid, and a LONG array is `additionalItems`' to
+// judge. Binding the tuple form to `.builder()` would therefore reject
+// documents the schema permits. The composite below is the same rule KIND,
+// with the draft's semantics.
+// ===========================================================================
+const create_chain_node_1 = require("../chain/create-chain-node");
+const create_field_slots_1 = require("../chain/create-field-slots");
+const create_rule_1 = require("../plugin-kit/create-rule");
+const apply_keyword_binding_1 = require("./apply-keyword-binding");
+const keyword_map_array_1 = require("./keyword-map-array");
+const types_1 = require("../types");
+const collect_definitions_1 = require("./collect-definitions");
+/** The declaration step for "every element of this array". */
+exports.EACH_STEP = "[*]";
+const NO_CHILDREN = Object.freeze([]);
+const NO_RULES = Object.freeze([]);
+/** True for the tuple form of `items`, which is an ARRAY of schemas. */
+function isTupleItems(items) {
+    return (0, types_1.isArray)(items);
+}
+/**
+ * The single form only. The tuple form gets no child path: element 0 and
+ * element 1 obey DIFFERENT schemas, and one declared `[*]` cannot say that.
+ */
+function readItemChildren(schema) {
+    const items = schema.items;
+    if (items === undefined || isTupleItems(items))
+        return NO_CHILDREN;
+    return Object.freeze([{ step: exports.EACH_STEP, schema: items, isRequired: false }]);
+}
+/**
+ * Element i against position i, extra elements against `additionalItems`.
+ * A non-array passes, a short array passes, and `additionalItems: false`
+ * becomes the schema that matches nothing (collect-definitions), so the
+ * "no extra elements" case needs no fourth branch kind.
+ */
+function applyPositionally(runners, positionCount, hasRest) {
+    return (value, ctx) => {
+        if (!(0, types_1.isArray)(value))
+            return types_1.PASS;
+        for (let index = 0; index < value.length; index += 1) {
+            const runner = index < positionCount
+                ? runners[index]
+                : hasRest
+                    ? runners[positionCount]
+                    : undefined;
+            if (runner === undefined)
+                continue;
+            const outcome = runner.run(value[index], ctx);
+            if (!outcome.ok)
+                return (0, types_1.fail)({ ...outcome.detail, index });
+        }
+        return types_1.PASS;
+    };
+}
+function describePosition(index) {
+    return index < 0
+        ? "An element does not match the schema declared for its position"
+        : `Element ${String(index)} does not match the schema declared for it`;
+}
+function composeTupleItems(schema, context) {
+    const items = schema.items;
+    if (items === undefined || !isTupleItems(items))
+        return NO_RULES;
+    const branches = items.map((position, index) => context.toBranch(`position:${String(index)}`, position));
+    const rest = schema.additionalItems;
+    const hasRest = rest !== undefined;
+    if (rest !== undefined)
+        branches.push(context.toBranch("rest", rest));
+    const positionCount = items.length;
+    return Object.freeze([
+        (0, create_rule_1.composite)({
+            code: "items",
+            severity: context.build.config.defaultSeverity,
+            branches,
+            combine: (runners) => applyPositionally(runners, positionCount, hasRest),
+            describe: (detail) => describePosition((0, types_1.isNumber)(detail.index) ? detail.index : -1),
+            buildMessageContext: () => ({}),
+        }),
+    ]);
+}
+/**
+ * `contains` is EXISTENTIAL: at least one element matches. arrayContains owns
+ * that reduction, and its default bounds (min 1, no max) are exactly the
+ * draft's, so this is one call and no arithmetic.
+ */
+function composeContains(schema, context) {
+    const contains = schema.contains;
+    if (contains === undefined)
+        return NO_RULES;
+    const element = context.collectSubSchemaRules((0, collect_definitions_1.toSchemaObject)(contains));
+    return Object.freeze([
+        context.bag.arrayContains.build(context.ruleContextFor(context.bag.arrayContains.name, "contains"), element),
+    ]);
+}
+/**
+ * The three array keywords that BIND. `minItems` maps to the method `minLength`
+ * and `maxItems` to `maxLength`; writing "minItems" as the method name does not
+ * compile (keyword-map-array.ts), which is the C2 regression made impossible.
+ * `uniqueItems: false` never reaches its binding: §6.4.3 gives it no effect and
+ * the binding's value type is `true`.
+ */
+function declareArrayRules(schema, context) {
+    let chain = (0, create_field_slots_1.createFieldSlots)(context.bag, context.build).array;
+    if (schema.minItems !== undefined) {
+        chain = (0, apply_keyword_binding_1.applyKeywordBinding)(chain, keyword_map_array_1.minItemsBinding, schema.minItems);
+    }
+    if (schema.maxItems !== undefined) {
+        chain = (0, apply_keyword_binding_1.applyKeywordBinding)(chain, keyword_map_array_1.maxItemsBinding, schema.maxItems);
+    }
+    if (schema.uniqueItems === true) {
+        chain = (0, apply_keyword_binding_1.applyKeywordBinding)(chain, keyword_map_array_1.uniqueItemsBinding, true);
+    }
+    return (0, create_chain_node_1.readChainRules)(chain) ?? NO_RULES;
+}

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

@@ -0,0 +1,134 @@
+// ===========================================================================
+// L8  src/json-schema/flatten-array-schema.ts — `items`, `additionalItems`,
+// `contains`.
+//
+// TWO SHAPES, ONE KEYWORD. `items` is either a schema (every element) or an
+// ARRAY of schemas (position i constrains element i). 1.x read only the first
+// shape and guessed the method name `tupleBuilder` for the second, which is not
+// a chain method, so the tuple form silently constrained nothing.
+//
+//   single form  ->  a CHILD DECLARATION at `path[*]`. That is better than
+//                    `.each()` here: the element gets a real declared path, so
+//                    its own `properties` become `path[*].name` and an issue
+//                    renders as `tags[2].name` rather than as a nested cause.
+//   tuple form   ->  ONE composite, built from create-rule.
+//
+// WHY NOT tupleBuilder (measured, not assumed): tupleBuilderPlugin rejects a
+// NON-ARRAY and enforces a LENGTH — exactly `value.length !== positions.length`
+// without a rest chain, and `value.length < positions.length` with one. Draft-07
+// §6.4 / §9.3.1 does neither: a non-array is not an array constraint's business
+// at all, a SHORT array is valid, and a LONG array is `additionalItems`' to
+// judge. Binding the tuple form to `.builder()` would therefore reject
+// documents the schema permits. The composite below is the same rule KIND,
+// with the draft's semantics.
+// ===========================================================================
+import { readChainRules } from "../chain/create-chain-node.mjs";
+import { createFieldSlots } from "../chain/create-field-slots.mjs";
+import { composite } from "../plugin-kit/create-rule.mjs";
+import { applyKeywordBinding } from "./apply-keyword-binding.mjs";
+import { maxItemsBinding, minItemsBinding, uniqueItemsBinding, } from "./keyword-map-array.mjs";
+import { PASS, fail, isArray, isNumber } from "../types/index.mjs";
+import { toSchemaObject } from "./collect-definitions.mjs";
+/** The declaration step for "every element of this array". */
+export const EACH_STEP = "[*]";
+const NO_CHILDREN = Object.freeze([]);
+const NO_RULES = Object.freeze([]);
+/** True for the tuple form of `items`, which is an ARRAY of schemas. */
+function isTupleItems(items) {
+    return isArray(items);
+}
+/**
+ * The single form only. The tuple form gets no child path: element 0 and
+ * element 1 obey DIFFERENT schemas, and one declared `[*]` cannot say that.
+ */
+export function readItemChildren(schema) {
+    const items = schema.items;
+    if (items === undefined || isTupleItems(items))
+        return NO_CHILDREN;
+    return Object.freeze([{ step: EACH_STEP, schema: items, isRequired: false }]);
+}
+/**
+ * Element i against position i, extra elements against `additionalItems`.
+ * A non-array passes, a short array passes, and `additionalItems: false`
+ * becomes the schema that matches nothing (collect-definitions), so the
+ * "no extra elements" case needs no fourth branch kind.
+ */
+function applyPositionally(runners, positionCount, hasRest) {
+    return (value, ctx) => {
+        if (!isArray(value))
+            return PASS;
+        for (let index = 0; index < value.length; index += 1) {
+            const runner = index < positionCount
+                ? runners[index]
+                : hasRest
+                    ? runners[positionCount]
+                    : undefined;
+            if (runner === undefined)
+                continue;
+            const outcome = runner.run(value[index], ctx);
+            if (!outcome.ok)
+                return fail({ ...outcome.detail, index });
+        }
+        return PASS;
+    };
+}
+function describePosition(index) {
+    return index < 0
+        ? "An element does not match the schema declared for its position"
+        : `Element ${String(index)} does not match the schema declared for it`;
+}
+export function composeTupleItems(schema, context) {
+    const items = schema.items;
+    if (items === undefined || !isTupleItems(items))
+        return NO_RULES;
+    const branches = items.map((position, index) => context.toBranch(`position:${String(index)}`, position));
+    const rest = schema.additionalItems;
+    const hasRest = rest !== undefined;
+    if (rest !== undefined)
+        branches.push(context.toBranch("rest", rest));
+    const positionCount = items.length;
+    return Object.freeze([
+        composite({
+            code: "items",
+            severity: context.build.config.defaultSeverity,
+            branches,
+            combine: (runners) => applyPositionally(runners, positionCount, hasRest),
+            describe: (detail) => describePosition(isNumber(detail.index) ? detail.index : -1),
+            buildMessageContext: () => ({}),
+        }),
+    ]);
+}
+/**
+ * `contains` is EXISTENTIAL: at least one element matches. arrayContains owns
+ * that reduction, and its default bounds (min 1, no max) are exactly the
+ * draft's, so this is one call and no arithmetic.
+ */
+export function composeContains(schema, context) {
+    const contains = schema.contains;
+    if (contains === undefined)
+        return NO_RULES;
+    const element = context.collectSubSchemaRules(toSchemaObject(contains));
+    return Object.freeze([
+        context.bag.arrayContains.build(context.ruleContextFor(context.bag.arrayContains.name, "contains"), element),
+    ]);
+}
+/**
+ * The three array keywords that BIND. `minItems` maps to the method `minLength`
+ * and `maxItems` to `maxLength`; writing "minItems" as the method name does not
+ * compile (keyword-map-array.ts), which is the C2 regression made impossible.
+ * `uniqueItems: false` never reaches its binding: §6.4.3 gives it no effect and
+ * the binding's value type is `true`.
+ */
+export function declareArrayRules(schema, context) {
+    let chain = createFieldSlots(context.bag, context.build).array;
+    if (schema.minItems !== undefined) {
+        chain = applyKeywordBinding(chain, minItemsBinding, schema.minItems);
+    }
+    if (schema.maxItems !== undefined) {
+        chain = applyKeywordBinding(chain, maxItemsBinding, schema.maxItems);
+    }
+    if (schema.uniqueItems === true) {
+        chain = applyKeywordBinding(chain, uniqueItemsBinding, true);
+    }
+    return readChainRules(chain) ?? NO_RULES;
+}

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

@@ -0,0 +1,20 @@
+import type { Draft07Schema, Draft07SchemaObject } from "./draft07.types";
+import type { ChildSchema } from "./structural-expansion.types";
+export interface SchemaFieldDeclaration {
+    readonly path: string;
+    readonly schema: Draft07SchemaObject;
+    readonly isRequired: boolean;
+}
+export type ReadChildSchemas = (schema: Draft07SchemaObject) => readonly ChildSchema[];
+/** `[*]` trails its key; every other step is a `.`-joined property name. */
+export declare function joinDeclaredPath(parent: string, step: string): string;
+/** The root plus every arm of its `allOf`, transitively, all resolved. */
+export declare function collectRootNodes(root: Draft07Schema): readonly Draft07SchemaObject[];
+/**
+ * The root declarations come FIRST, one per `allOf` arm that carries a rule of
+ * its own, so two arms cannot silently overwrite each other's `minProperties`.
+ * `isRequired` is false: the root is always present (create-validator refuses a
+ * missing root before the plan runs), and a presence rule there would only add
+ * a second answer to a question already settled.
+ */
+export declare function flattenSchema(root: Draft07Schema, readChildren: ReadChildSchemas): readonly SchemaFieldDeclaration[];

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

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinDeclaredPath = joinDeclaredPath;
+exports.collectRootNodes = collectRootNodes;
+exports.flattenSchema = flattenSchema;
+// ===========================================================================
+// L8  src/json-schema/flatten-schema.ts — the document as a list of DECLARED
+// PATHS.
+//
+// `properties` nests; Luq declares. `{properties:{user:{properties:{address:
+// {properties:{street:{}}}}}}}` becomes the declaration `user.address.street`,
+// and `items` becomes `tags[*]`, so an issue renders as `tags[2].name` with the
+// real index rather than as a cause hanging off a parent object.
+//
+// THE ROOT IS A DECLARABLE PATH — as of the stage-27 gate, and it is why
+// `{type:"object", properties:{…}, additionalProperties:false}` converts at all.
+// parse-field-path still rejects "" (a CHILD path may not be empty), but
+// compile-schema maps ROOT_PATH onto the EMPTY TEMPLATE — the shape a composite
+// branch's own rules have always used — so a root keyword becomes a rule.
+//
+// 1.x dropped every root keyword in silence (skipping the `path === ""` entry
+// and calling `.strict()`, which has no runtime effect); step 25 refused them
+// loudly instead. Neither validated them. Now:
+//   * `properties` still becomes one DECLARED PATH per key, so an issue reads
+//     `user.age`, not "somewhere inside the root object";
+//   * `required` still distributes to those children, so a missing property is
+//     reported AT the property;
+//   * `allOf` is still merged arm by arm, so its children are declared too;
+//   * `type` is dropped: fromJsonSchema is object-rooted by construction;
+//   * EVERY OTHER rule-bearing keyword becomes a rule on the root declaration.
+// `properties` is kept in that residual node, and only there: it contributes no
+// rule, but createStructuralContext reads `declaredSiblingKeys` from it, which
+// is what a root-level `additionalProperties: false` needs to know.
+// ===========================================================================
+const declared_child_keys_1 = require("../compile/declared-child-keys");
+const reserved_segment_1 = require("../path/reserved-segment");
+const collect_definitions_1 = require("./collect-definitions");
+const flatten_array_schema_1 = require("./flatten-array-schema");
+/** Deep enough for any hand-written schema; a recursive one stops sooner. */
+const MAX_NESTING_DEPTH = 32;
+/**
+ * Root keywords that produce NO rule on the root declaration: the ones the
+ * flattener distributes itself (and would otherwise apply twice), plus the ones
+ * that assert nothing anywhere. Every other keyword stays in the residual node
+ * and reaches expandSchemaRules like any other field's schema.
+ */
+const ROOT_KEYWORDS_WITHOUT_A_ROOT_RULE = Object.freeze([
+    "$schema",
+    "$id",
+    "$ref",
+    "$comment",
+    "definitions",
+    "$defs",
+    "title",
+    "description",
+    "default",
+    "examples",
+    "readOnly",
+    "writeOnly",
+    "properties",
+    "required",
+    "allOf",
+    "type",
+]);
+/** `[*]` trails its key; every other step is a `.`-joined property name. */
+function joinDeclaredPath(parent, step) {
+    if (step === flatten_array_schema_1.EACH_STEP)
+        return `${parent}${flatten_array_schema_1.EACH_STEP}`;
+    (0, reserved_segment_1.assertDeclarableKey)(step, parent === "" ? step : `${parent}.${step}`);
+    return parent === "" ? step : `${parent}.${step}`;
+}
+/** The root plus every arm of its `allOf`, transitively, all resolved. */
+function collectRootNodes(root) {
+    const nodes = [];
+    const pending = [root];
+    while (pending.length > 0 && nodes.length < MAX_NESTING_DEPTH) {
+        const next = pending.shift();
+        if (next === undefined)
+            break;
+        const node = (0, collect_definitions_1.resolveSchemaNode)(next, root);
+        nodes.push(node);
+        for (const arm of node.allOf ?? [])
+            pending.push(arm);
+    }
+    return Object.freeze(nodes);
+}
+/** True when the node says anything the root declaration has to carry. */
+function hasRootRuleKeyword(node) {
+    return Object.keys(node).some((keyword) => !ROOT_KEYWORDS_WITHOUT_A_ROOT_RULE.includes(keyword));
+}
+/** 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;
+    return residual;
+}
+/** Children of the root, merged across the `allOf` arms, first arm winning. */
+function readRootChildren(nodes, readChildren) {
+    const merged = new Map();
+    for (const node of nodes) {
+        // Requiredness is read from the ROOT nodes themselves: readChildSchemas
+        // reports every child as not-required, because everywhere else a
+        // `required` array becomes a rule on the object that owns it. The root has
+        // no such object, so this is the one place it becomes child presence.
+        const required = node.required ?? [];
+        for (const child of readChildren(node)) {
+            const isRequired = required.includes(child.step);
+            const seen = merged.get(child.step);
+            if (seen === undefined) {
+                merged.set(child.step, { ...child, isRequired });
+                continue;
+            }
+            if (isRequired && !seen.isRequired) {
+                merged.set(child.step, { ...seen, isRequired: true });
+            }
+        }
+    }
+    return Object.freeze([...merged.values()]);
+}
+/**
+ * A `$ref` already on this branch is a RECURSIVE definition. Its declared paths
+ * are infinite and Luq declares finite ones, so the node's own rules are kept
+ * and its children are not expanded. objectRecursively is the plugin for that
+ * shape and it is not in the JSON Schema bag.
+ */
+function walkChild(parentPath, child, visitedRefs, depth, state) {
+    const path = joinDeclaredPath(parentPath, child.step);
+    const pointer = (0, collect_definitions_1.readRefPointer)(child.schema);
+    const node = (0, collect_definitions_1.resolveSchemaNode)(child.schema, state.root);
+    state.into.push({ path, schema: node, isRequired: child.isRequired });
+    const isRepeat = pointer !== undefined && visitedRefs.includes(pointer);
+    if (isRepeat || depth >= MAX_NESTING_DEPTH)
+        return;
+    const seen = pointer === undefined ? visitedRefs : [...visitedRefs, pointer];
+    for (const grandChild of state.readChildren(node)) {
+        walkChild(path, grandChild, seen, depth + 1, state);
+    }
+}
+/**
+ * The root declarations come FIRST, one per `allOf` arm that carries a rule of
+ * its own, so two arms cannot silently overwrite each other's `minProperties`.
+ * `isRequired` is false: the root is always present (create-validator refuses a
+ * missing root before the plan runs), and a presence rule there would only add
+ * a second answer to a question already settled.
+ */
+function flattenSchema(root, readChildren) {
+    const nodes = collectRootNodes(root);
+    const state = { root, readChildren, into: [] };
+    for (const node of nodes) {
+        if (!hasRootRuleKeyword(node))
+            continue;
+        state.into.push({
+            path: declared_child_keys_1.ROOT_PATH,
+            schema: dropDistributedKeywords(node),
+            isRequired: false,
+        });
+    }
+    for (const child of readRootChildren(nodes, readChildren)) {
+        walkChild("", child, Object.freeze([]), 0, state);
+    }
+    return Object.freeze(state.into);
+}

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

@@ -0,0 +1,157 @@
+// ===========================================================================
+// L8  src/json-schema/flatten-schema.ts — the document as a list of DECLARED
+// PATHS.
+//
+// `properties` nests; Luq declares. `{properties:{user:{properties:{address:
+// {properties:{street:{}}}}}}}` becomes the declaration `user.address.street`,
+// and `items` becomes `tags[*]`, so an issue renders as `tags[2].name` with the
+// real index rather than as a cause hanging off a parent object.
+//
+// THE ROOT IS A DECLARABLE PATH — as of the stage-27 gate, and it is why
+// `{type:"object", properties:{…}, additionalProperties:false}` converts at all.
+// parse-field-path still rejects "" (a CHILD path may not be empty), but
+// compile-schema maps ROOT_PATH onto the EMPTY TEMPLATE — the shape a composite
+// branch's own rules have always used — so a root keyword becomes a rule.
+//
+// 1.x dropped every root keyword in silence (skipping the `path === ""` entry
+// and calling `.strict()`, which has no runtime effect); step 25 refused them
+// loudly instead. Neither validated them. Now:
+//   * `properties` still becomes one DECLARED PATH per key, so an issue reads
+//     `user.age`, not "somewhere inside the root object";
+//   * `required` still distributes to those children, so a missing property is
+//     reported AT the property;
+//   * `allOf` is still merged arm by arm, so its children are declared too;
+//   * `type` is dropped: fromJsonSchema is object-rooted by construction;
+//   * EVERY OTHER rule-bearing keyword becomes a rule on the root declaration.
+// `properties` is kept in that residual node, and only there: it contributes no
+// rule, but createStructuralContext reads `declaredSiblingKeys` from it, which
+// is what a root-level `additionalProperties: false` needs to know.
+// ===========================================================================
+import { ROOT_PATH } from "../compile/declared-child-keys.mjs";
+import { assertDeclarableKey } from "../path/reserved-segment.mjs";
+import { resolveSchemaNode, readRefPointer } from "./collect-definitions.mjs";
+import { EACH_STEP } from "./flatten-array-schema.mjs";
+/** Deep enough for any hand-written schema; a recursive one stops sooner. */
+const MAX_NESTING_DEPTH = 32;
+/**
+ * Root keywords that produce NO rule on the root declaration: the ones the
+ * flattener distributes itself (and would otherwise apply twice), plus the ones
+ * that assert nothing anywhere. Every other keyword stays in the residual node
+ * and reaches expandSchemaRules like any other field's schema.
+ */
+const ROOT_KEYWORDS_WITHOUT_A_ROOT_RULE = Object.freeze([
+    "$schema",
+    "$id",
+    "$ref",
+    "$comment",
+    "definitions",
+    "$defs",
+    "title",
+    "description",
+    "default",
+    "examples",
+    "readOnly",
+    "writeOnly",
+    "properties",
+    "required",
+    "allOf",
+    "type",
+]);
+/** `[*]` trails its key; every other step is a `.`-joined property name. */
+export function joinDeclaredPath(parent, step) {
+    if (step === EACH_STEP)
+        return `${parent}${EACH_STEP}`;
+    assertDeclarableKey(step, parent === "" ? step : `${parent}.${step}`);
+    return parent === "" ? step : `${parent}.${step}`;
+}
+/** The root plus every arm of its `allOf`, transitively, all resolved. */
+export function collectRootNodes(root) {
+    const nodes = [];
+    const pending = [root];
+    while (pending.length > 0 && nodes.length < MAX_NESTING_DEPTH) {
+        const next = pending.shift();
+        if (next === undefined)
+            break;
+        const node = resolveSchemaNode(next, root);
+        nodes.push(node);
+        for (const arm of node.allOf ?? [])
+            pending.push(arm);
+    }
+    return Object.freeze(nodes);
+}
+/** True when the node says anything the root declaration has to carry. */
+function hasRootRuleKeyword(node) {
+    return Object.keys(node).some((keyword) => !ROOT_KEYWORDS_WITHOUT_A_ROOT_RULE.includes(keyword));
+}
+/** 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;
+    return residual;
+}
+/** Children of the root, merged across the `allOf` arms, first arm winning. */
+function readRootChildren(nodes, readChildren) {
+    const merged = new Map();
+    for (const node of nodes) {
+        // Requiredness is read from the ROOT nodes themselves: readChildSchemas
+        // reports every child as not-required, because everywhere else a
+        // `required` array becomes a rule on the object that owns it. The root has
+        // no such object, so this is the one place it becomes child presence.
+        const required = node.required ?? [];
+        for (const child of readChildren(node)) {
+            const isRequired = required.includes(child.step);
+            const seen = merged.get(child.step);
+            if (seen === undefined) {
+                merged.set(child.step, { ...child, isRequired });
+                continue;
+            }
+            if (isRequired && !seen.isRequired) {
+                merged.set(child.step, { ...seen, isRequired: true });
+            }
+        }
+    }
+    return Object.freeze([...merged.values()]);
+}
+/**
+ * A `$ref` already on this branch is a RECURSIVE definition. Its declared paths
+ * are infinite and Luq declares finite ones, so the node's own rules are kept
+ * and its children are not expanded. objectRecursively is the plugin for that
+ * shape and it is not in the JSON Schema bag.
+ */
+function walkChild(parentPath, child, visitedRefs, depth, state) {
+    const path = joinDeclaredPath(parentPath, child.step);
+    const pointer = readRefPointer(child.schema);
+    const node = resolveSchemaNode(child.schema, state.root);
+    state.into.push({ path, schema: node, isRequired: child.isRequired });
+    const isRepeat = pointer !== undefined && visitedRefs.includes(pointer);
+    if (isRepeat || depth >= MAX_NESTING_DEPTH)
+        return;
+    const seen = pointer === undefined ? visitedRefs : [...visitedRefs, pointer];
+    for (const grandChild of state.readChildren(node)) {
+        walkChild(path, grandChild, seen, depth + 1, state);
+    }
+}
+/**
+ * The root declarations come FIRST, one per `allOf` arm that carries a rule of
+ * its own, so two arms cannot silently overwrite each other's `minProperties`.
+ * `isRequired` is false: the root is always present (create-validator refuses a
+ * missing root before the plan runs), and a presence rule there would only add
+ * a second answer to a question already settled.
+ */
+export function flattenSchema(root, readChildren) {
+    const nodes = collectRootNodes(root);
+    const state = { root, readChildren, into: [] };
+    for (const node of nodes) {
+        if (!hasRootRuleKeyword(node))
+            continue;
+        state.into.push({
+            path: ROOT_PATH,
+            schema: dropDistributedKeywords(node),
+            isRequired: false,
+        });
+    }
+    for (const child of readRootChildren(nodes, readChildren)) {
+        walkChild("", child, Object.freeze([]), 0, state);
+    }
+    return Object.freeze(state.into);
+}

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;
+};