@cplieger/deadset-ts 8.0.0-dev.6 → 8.0.0-dev.8

package/dist/src/schema.js

@@ -1,394 +1,371 @@
-import { ConfigError } from "./config.js";
-const leaf = { kind: "leaf" };
-const integer = { kind: "leaf", integer: true };
-/** A list of declarations, each entry in one of the three shapes the `ts` section states. */
-const declarations = {
-    kind: "list",
-    members: { symbol: leaf, module: leaf, name: leaf, global: leaf },
-};
 /**
- * The closed key list the Contract's configuration schema declares, derived from
- * that schema key by key. A test pins the two equal, so a Contract change that
- * adds a key fails there rather than being silently unimplemented.
+ * Holds a value to a JSON Schema the generator copies from the Contract. It evaluates the
+ * keywords the Contract's schemas use; the schemas' patterns are written to match alike in
+ * RE2 and in ECMAScript.
  */
-export const SCHEMA_ROOT = {
-    kind: "section",
-    members: {
-        contract_version: leaf,
-        target: {
-            kind: "section",
-            members: { kind: { kind: "object", members: { go: leaf, ts: leaf } } },
-        },
-        analysis: {
-            kind: "section",
-            members: {
-                languages: leaf,
-                min_confidence: leaf,
-                generated_files: leaf,
-                consumer_tests: leaf,
-                configurations: {
-                    kind: "list",
-                    members: { id: leaf, os: leaf, arch: leaf, tags: leaf, project: leaf },
-                },
-                matrix: { kind: "section", members: { complete: leaf } },
-                template_dirs: leaf,
-                template_delimiters: {
-                    kind: "object",
-                    members: { left: leaf, right: leaf },
-                },
-            },
-        },
-        consumers: { kind: "section", members: { complete: leaf } },
-        roots: { kind: "section", members: { patterns: leaf } },
-        severity: { kind: "map" },
-        exemptions: { kind: "section", members: { disabled: leaf } },
-        reporters: {
-            kind: "section",
-            members: {
-                formats: leaf,
-                sort: leaf,
-                cascade: leaf,
-                max_findings: integer,
-                fail_on: leaf,
-            },
-        },
-        providers: {
-            kind: "section",
-            members: {
-                analyzers: {
-                    kind: "list",
-                    members: {
-                        name: leaf,
-                        languages: leaf,
-                        command: leaf,
-                        source: leaf,
-                        version: leaf,
-                        digest: leaf,
-                    },
-                },
-            },
-        },
-        go: { kind: "section", members: {} },
-        ts: {
-            kind: "section",
-            members: {
-                test_files: leaf,
-                entry_files: leaf,
-                component_extensions: leaf,
-                disabled_conventions: leaf,
-                injection_registrations: declarations,
-                lifecycle_contracts: {
-                    kind: "list",
-                    members: { components: declarations, bases: declarations, members: leaf },
-                },
-                serializers: declarations,
-                roots_complete: leaf,
-            },
-        },
-        provenance: { kind: "map" },
-    },
-};
-/** The name of the severity object, whose member names the key list leaves open. */
-export const SEVERITY_SECTION = "severity";
+import { isRecord, pointerOf, pointerSegments } from "./json-document.js";
+import { bytewise } from "./text/compare.js";
 /**
- * The node one member name resolves to, and whether the key list declares it. A
- * member of an open object, and any member below a setting, resolves to a leaf,
- * so the walk descends far enough to find a repeated member at any depth.
+ * Every keyword the validator evaluates or knows to carry no assertion. A schema naming
+ * another fails every check rather than passing values the keyword would refuse.
  */
-function memberOf(node, name) {
-    if (node.kind === "section" || node.kind === "list" || node.kind === "object") {
-        const members = node.members ?? {};
-        return Object.hasOwn(members, name) ? members[name] : undefined;
+const KEYWORDS = new Set([
+    ...["$schema", "$id", "$comment", "$defs", "title", "description", "default", "examples"],
+    ...["$ref", "type", "enum", "const", "pattern", "minLength", "minimum", "maximum"],
+    ...["properties", "additionalProperties", "propertyNames", "required", "minProperties"],
+    ...["items", "minItems", "maxItems", "uniqueItems"],
+    ...["allOf", "anyOf", "oneOf", "not", "if", "then", "else"],
+]);
+const patterns = new Map();
+function pattern(source) {
+    let held = patterns.get(source);
+    if (held === undefined) {
+        held = new RegExp(source, "u");
+        patterns.set(source, held);
     }
-    return leaf;
+    return held;
 }
-function joinKey(at, name) {
-    return at === "" ? name : `${at}.${name}`;
-}
-function collect(node, at, keys, settingsOnly) {
-    for (const [name, child] of Object.entries(node.members ?? {})) {
-        const path = joinKey(at, name);
-        if (!settingsOnly) {
-            keys.push(path);
-            collect(child, child.kind === "list" ? `${path}[]` : path, keys, settingsOnly);
-            continue;
-        }
-        if (child.kind === "leaf" || child.kind === "list" || child.kind === "object") {
-            keys.push(path);
-            continue;
-        }
-        collect(child, path, keys, settingsOnly);
+function typeOf(value) {
+    if (value === null) {
+        return "null";
     }
-}
-/**
- * Every key the closed key list declares, as a dotted path, in ascending order:
- * the sections, the settings, and the two open objects. A list's entry members
- * are spelled under the list's own path followed by empty brackets.
- */
-export function declaredKeys() {
-    const keys = [];
-    collect(SCHEMA_ROOT, "", keys, false);
-    return keys.sort();
-}
-/**
- * The dotted path of every setting that holds one value, in ascending order. A
- * list and a setting written as an object are each one setting, their members not
- * addressable on their own, and the severity object is not among them: it
- * resolves per code.
- */
-export function settingPaths() {
-    const paths = [];
-    collect(SCHEMA_ROOT, "", paths, true);
-    return paths.sort();
-}
-/**
- * Whether one dotted path names a setting a source may supply: a setting of the
- * closed key list, or one code of the severity object, whose member names the key
- * list leaves open. It is the predicate the command maps its own flag names
- * through, so a flag that would be refused as an unimplemented key is a failing
- * test rather than a flag nothing reads.
- *
- * A section holds no value of its own, so `analysis` is false. A setting written
- * as an object is supplied whole, so `analysis.template_delimiters` is true and
- * `analysis.template_delimiters.left` is false. A severity code is a declared
- * setting whatever it names, so `severity.DS9999` is true here and refused by
- * resolution: this answers the shape of a path, and resolution answers the
- * vocabulary.
- */
-export function declaresSetting(path) {
-    if (settingPaths().includes(path)) {
-        return true;
+    if (Array.isArray(value)) {
+        return "array";
     }
-    const dot = path.indexOf(".");
-    if (dot < 0) {
-        return false;
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? "integer" : "number";
     }
-    const code = path.slice(dot + 1);
-    return path.slice(0, dot) === SEVERITY_SECTION && code !== "" && !code.includes(".");
+    return typeof value;
 }
-/** The Levenshtein distance between two strings, counted in code points. */
-function editDistance(a, b) {
-    const from = Array.from(a);
-    const to = Array.from(b);
-    let previous = Array.from({ length: to.length + 1 }, (_unused, index) => index);
-    let current = new Array(to.length + 1).fill(0);
-    for (let i = 1; i <= from.length; i += 1) {
-        current[0] = i;
-        for (let j = 1; j <= to.length; j += 1) {
-            const substitution = (previous[j - 1] ?? 0) + (from[i - 1] === to[j - 1] ? 0 : 1);
-            current[j] = Math.min(substitution, (previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1);
-        }
-        [previous, current] = [current, previous];
+function hasType(value, name) {
+    const held = typeOf(value);
+    return held === name || (name === "number" && held === "integer");
+}
+/** The types a schema names, none where it names no type. */
+function typesOf(schema) {
+    const types = schema["type"];
+    if (types === undefined) {
+        return [];
     }
-    return previous[to.length] ?? 0;
+    return (Array.isArray(types) ? types : [types]).filter((one) => typeof one === "string");
 }
-function sharedSegments(a, b) {
-    let shared = 0;
-    while (shared < a.length && shared < b.length && a[shared] === b[shared]) {
-        shared += 1;
+/** One value's encoding with object members sorted, so two equal values encode alike. */
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(",")}]`;
+    }
+    if (isRecord(value)) {
+        return `{${Object.keys(value)
+            .sort(bytewise)
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(",")}}`;
     }
-    return shared;
+    return JSON.stringify(value);
 }
-/**
- * The implemented key closest to `key`: the one sharing the most leading dotted
- * segments, and among those the smallest edit distance over the whole path, ties
- * broken in ascending order.
- */
-export function nearestKey(key) {
-    const segments = key.split(".");
-    let nearest = "";
-    let bestShared = -1;
-    let bestDistance = 0;
-    for (const candidate of declaredKeys()) {
-        const shared = sharedSegments(segments, candidate.split("."));
-        const distance = editDistance(key, candidate);
-        if (shared < bestShared || (shared === bestShared && distance >= bestDistance)) {
-            continue;
-        }
-        nearest = candidate;
-        bestShared = shared;
-        bestDistance = distance;
+/** A string's length in code points, which JSON Schema's minLength counts. */
+function codePoints(value) {
+    let counted = 0;
+    for (const _point of value) {
+        counted += 1;
     }
-    return nearest;
+    return counted;
 }
-/** A refusal of a document that is not one instance of the closed key list. */
-export function malformed(label, path, detail) {
-    const message = path === "" ? `${label}: ${detail}` : `${label}: ${path}: ${detail}`;
-    return new ConfigError("malformed", path, message);
+/** The schemas of a list keyword, none where the schema does not write it. */
+function listOf(schema, keyword) {
+    const held = schema[keyword];
+    return Array.isArray(held) ? held : [];
 }
-/**
- * A refusal of a key the closed key list does not declare, naming the nearest key
- * it does.
- */
-function unimplementedKey(label, path) {
-    const nearest = nearestKey(path);
-    let hint = "";
-    if (nearest === path) {
-        hint = `. ${JSON.stringify(path)} is one setting written as nested objects, not as one key`;
+/** Whether a reader fixes refusal `a` before `b`: an object's before one inside it, then by kind. */
+function before(a, b) {
+    if (a.pointer === b.pointer) {
+        return rank(a) < rank(b);
     }
-    else if (nearest !== "") {
-        hint = `. The nearest implemented key is ${JSON.stringify(nearest)}`;
+    return b.pointer.startsWith(`${a.pointer}/`);
+}
+/** The order of the refusals of one place: an undeclared member, a missing one, any other. */
+function rank(refusal) {
+    if (refusal.keyword === "additionalProperties" || refusal.keyword === "propertyNames") {
+        return 0;
     }
-    return new ConfigError("unimplemented-key", path, `${label}: key ${JSON.stringify(path)} is not implemented${hint}`);
+    return refusal.keyword === "required" ? 1 : 2;
 }
-const SPACE = new Set([0x20, 0x09, 0x0a, 0x0d]);
-function skipSpace(cursor) {
-    while (cursor.at < cursor.text.length && SPACE.has(cursor.text.charCodeAt(cursor.at))) {
-        cursor.at += 1;
+/** The value one JSON Pointer segment names inside `value`, or undefined. */
+function valueAt(value, segment) {
+    if (Array.isArray(value)) {
+        return /^[0-9]+$/u.test(segment) ? value[Number(segment)] : undefined;
     }
+    return isRecord(value) && Object.hasOwn(value, segment) ? value[segment] : undefined;
 }
 /**
- * The string literal at the cursor, decoded by the standard library: the walk
- * finds the literal's extent and the parse reads it, so an escaped member name
- * compares equal to the name it spells.
+ * The schema `properties` declares for the member `name`, or undefined: a member named as an
+ * `Object.prototype` property, such as `__proto__`, is declared only where it is written.
  */
-function readName(cursor, at, label) {
-    const start = cursor.at;
-    cursor.at += 1;
-    while (cursor.at < cursor.text.length) {
-        const ch = cursor.text.charCodeAt(cursor.at);
-        if (ch === 0x5c) {
-            cursor.at += 2;
-            continue;
-        }
-        cursor.at += 1;
-        if (ch === 0x22) {
-            return JSON.parse(cursor.text.slice(start, cursor.at));
+function declaredMember(properties, name) {
+    return Object.hasOwn(properties, name) ? properties[name] : undefined;
+}
+/** The keyword checks over one set of schema documents, each named as a `$ref` names it. */
+class Checker {
+    documents;
+    constructor(documents) {
+        this.documents = documents;
+    }
+    resolve(doc, ref) {
+        const [file = "", pointer = ""] = ref.split("#");
+        const target = file === "" ? doc : file;
+        let schema = this.documents[target];
+        for (const token of pointerSegments(pointer)) {
+            schema = isRecord(schema) ? schema[token] : undefined;
         }
+        if (!isRecord(schema)) {
+            throw new Error(`schema: ${ref} names no schema`);
+        }
+        return [target, schema];
     }
-    throw malformed(label, at, "a member name is not terminated");
-}
-function skipScalar(cursor) {
-    while (cursor.at < cursor.text.length) {
-        const ch = cursor.text.charCodeAt(cursor.at);
-        if (ch === 0x2c || ch === 0x7d || ch === 0x5d || SPACE.has(ch)) {
+    refusals(doc, schema, value, at) {
+        const found = [];
+        this.check(doc, schema, value, at, found);
+        return found;
+    }
+    matches(doc, schema, value, at) {
+        return this.refusals(doc, schema, value, at).length === 0;
+    }
+    check(doc, schema, value, at, found) {
+        for (const keyword of Object.keys(schema)) {
+            if (!KEYWORDS.has(keyword) && !keyword.startsWith("x-")) {
+                throw new Error(`schema: the keyword ${keyword} is not one this validator evaluates`);
+            }
+        }
+        const refuse = (keyword, reason, member = "") => {
+            found.push({ pointer: at, keyword, reason, member });
+        };
+        if (typeof schema["$ref"] === "string") {
+            const [target, referenced] = this.resolve(doc, schema["$ref"]);
+            this.check(target, referenced, value, at, found);
+        }
+        const named = typesOf(schema);
+        if (named.length > 0 && !named.some((one) => hasType(value, one))) {
+            refuse("type", `the value is ${typeOf(value)}, want ${named.join(", ")}`);
             return;
         }
-        cursor.at += 1;
-    }
-}
-/** A number the document writes as an optional minus sign and digits alone. */
-const INTEGER_TEXT = /^-?[0-9]+$/u;
-/** The start of a JSON number: a minus sign or a digit. */
-const NUMBER_START = /^[-0-9]/u;
-/**
- * Refuses a number written with a fraction or an exponent where the key list
- * declares an integer. A parse reads `100.0` and `1e2` as the integer 100, so only
- * the text can tell them apart. A scalar that is no number is the decoder's to
- * refuse by its type.
- */
-function checkInteger(text, at, label) {
-    if (NUMBER_START.test(text) && !INTEGER_TEXT.test(text)) {
-        throw malformed(label, at, `${text} is written with a fraction or an exponent, and an integer is digits alone`);
+        this.checkValue(schema, value, refuse);
+        if (Array.isArray(value)) {
+            this.checkArray(doc, schema, value, at, found, refuse);
+        }
+        else if (isRecord(value)) {
+            this.checkObject(doc, schema, value, at, found, refuse);
+        }
+        this.checkApplicators(doc, schema, value, at, found, refuse);
     }
-}
-function walkValue(cursor, at, node, label) {
-    skipSpace(cursor);
-    const ch = cursor.text.charCodeAt(cursor.at);
-    if (ch === 0x7b) {
-        cursor.at += 1;
-        walkObject(cursor, at, node, label);
-        return;
+    checkValue(schema, value, refuse) {
+        const values = schema["enum"];
+        if (Array.isArray(values) && !values.some((one) => canonical(one) === canonical(value))) {
+            refuse("enum", `${canonical(value)} is not one of ${values.map(canonical).join(", ")}`);
+        }
+        if (schema["const"] !== undefined && canonical(schema["const"]) !== canonical(value)) {
+            refuse("const", `${canonical(value)} is not ${canonical(schema["const"])}`);
+        }
+        if (typeof value === "string") {
+            if (typeof schema["pattern"] === "string" && !pattern(schema["pattern"]).test(value)) {
+                refuse("pattern", `${JSON.stringify(value)} does not match ${schema["pattern"]}`);
+            }
+            if (typeof schema["minLength"] === "number" && codePoints(value) < schema["minLength"]) {
+                refuse("minLength", `${JSON.stringify(value)} is shorter than ${String(schema["minLength"])} characters`);
+            }
+        }
+        if (typeof value === "number") {
+            if (typeof schema["minimum"] === "number" && value < schema["minimum"]) {
+                refuse("minimum", `${String(value)} is below ${String(schema["minimum"])}`);
+            }
+            if (typeof schema["maximum"] === "number" && value > schema["maximum"]) {
+                refuse("maximum", `${String(value)} is above ${String(schema["maximum"])}`);
+            }
+        }
     }
-    if (ch === 0x5b) {
-        cursor.at += 1;
-        walkArray(cursor, at, node, label);
-        return;
+    checkObject(doc, schema, value, at, found, refuse) {
+        const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+        const additional = schema["additionalProperties"];
+        const names = schema["propertyNames"];
+        for (const name of Object.keys(value).sort(bytewise)) {
+            const [refusedName] = isRecord(names) ? this.refusals(doc, names, name, at) : [];
+            if (refusedName !== undefined) {
+                refuse("propertyNames", `the member name ${JSON.stringify(name)}: ${refusedName.reason}`, name);
+            }
+            const member = `${at}${pointerOf([name])}`;
+            const declared = declaredMember(properties, name);
+            if (isRecord(declared)) {
+                this.check(doc, declared, value[name], member, found);
+            }
+            else if (additional === false) {
+                refuse("additionalProperties", `the member ${JSON.stringify(name)} is not one the schema declares`, name);
+            }
+            else if (isRecord(additional)) {
+                this.check(doc, additional, value[name], member, found);
+            }
+        }
+        for (const name of Array.isArray(schema["required"]) ? schema["required"] : []) {
+            if (!Object.hasOwn(value, name)) {
+                refuse("required", `the member ${JSON.stringify(name)} is absent`, name);
+            }
+        }
+        const fewest = schema["minProperties"];
+        if (typeof fewest === "number" && Object.keys(value).length < fewest) {
+            refuse("minProperties", `the object holds ${String(Object.keys(value).length)} members, fewer than ${String(fewest)}`);
+        }
     }
-    if (ch === 0x22) {
-        readName(cursor, at, label);
-        return;
+    checkArray(doc, schema, value, at, found, refuse) {
+        const items = schema["items"];
+        if (isRecord(items)) {
+            value.forEach((item, i) => {
+                this.check(doc, items, item, `${at}/${String(i)}`, found);
+            });
+        }
+        if (typeof schema["minItems"] === "number" && value.length < schema["minItems"]) {
+            refuse("minItems", `the array holds ${String(value.length)} items, fewer than ${String(schema["minItems"])}`);
+        }
+        if (typeof schema["maxItems"] === "number" && value.length > schema["maxItems"]) {
+            refuse("maxItems", `the array holds ${String(value.length)} items, more than ${String(schema["maxItems"])}`);
+        }
+        if (schema["uniqueItems"] === true && new Set(value.map(canonical)).size !== value.length) {
+            refuse("uniqueItems", "the array lists one value twice");
+        }
     }
-    const start = cursor.at;
-    skipScalar(cursor);
-    if (node.integer === true) {
-        checkInteger(cursor.text.slice(start, cursor.at), at, label);
+    checkApplicators(doc, schema, value, at, found, refuse) {
+        for (const each of listOf(schema, "allOf")) {
+            this.check(doc, each, value, at, found);
+        }
+        const matching = (keyword) => listOf(schema, keyword).filter((each) => this.matches(doc, each, value, at)).length;
+        if (schema["anyOf"] !== undefined && matching("anyOf") === 0) {
+            refuse("anyOf", "the value matches none of the alternatives");
+        }
+        if (schema["oneOf"] !== undefined && matching("oneOf") !== 1) {
+            refuse("oneOf", `the value matches ${String(matching("oneOf"))} of the alternatives, want exactly one`);
+        }
+        if (isRecord(schema["not"]) && this.matches(doc, schema["not"], value, at)) {
+            refuse("not", "the value matches a schema it must not match");
+        }
+        if (isRecord(schema["if"])) {
+            const branch = this.matches(doc, schema["if"], value, at) ? schema["then"] : schema["else"];
+            if (isRecord(branch)) {
+                this.check(doc, branch, value, at, found);
+            }
+        }
     }
-}
-function walkObject(cursor, at, node, label) {
-    const seen = new Set();
-    for (;;) {
-        skipSpace(cursor);
-        const ch = cursor.text.charCodeAt(cursor.at);
-        if (ch === 0x7d) {
-            cursor.at += 1;
-            return;
+    /**
+     * The refusal of `value` a reader fixes first, none for an instance: an object's
+     * refusal before any inside it, at one place an undeclared member, then a missing one,
+     * then any other, else the order the check finds them in. A oneOf no alternative
+     * matches is explained by the first refusal of the alternative the value was written
+     * for: the one whose type admits it, or of several, the one declaring the most of an
+     * object's members, then the fewest. Where two remain, the refusal is the oneOf's own.
+     */
+    first(doc, schema, value, at) {
+        const found = [];
+        this.check(doc, schema, value, at, found);
+        let first = found[0];
+        for (const other of found.slice(1)) {
+            if (first !== undefined && before(other, first)) {
+                first = other;
+            }
         }
-        if (ch === 0x2c) {
-            cursor.at += 1;
-            continue;
+        if (first?.keyword !== "oneOf") {
+            return first;
         }
-        if (ch !== 0x22) {
-            throw malformed(label, at, "a member name is expected");
+        let held = value;
+        let holders = [[doc, schema]];
+        for (const segment of pointerSegments(first.pointer.slice(at.length))) {
+            holders = holders.flatMap(([d, s]) => this.applied(d, s, held).flatMap(([d2, s2]) => this.member(d2, s2, held, segment)));
+            held = valueAt(held, segment);
         }
-        const name = readName(cursor, at, label);
-        const path = joinKey(at, name);
-        if (seen.has(name)) {
-            throw malformed(label, path, `member ${JSON.stringify(name)} is written twice, so neither value is chosen`);
+        for (const [d, holder] of holders) {
+            const alternatives = listOf(holder, "oneOf");
+            if (alternatives.some((each) => this.matches(d, each, held, first.pointer))) {
+                continue;
+            }
+            const alternative = closest(alternatives, held);
+            const inner = alternative && this.first(d, alternative, held, first.pointer);
+            if (inner !== undefined) {
+                return inner;
+            }
         }
-        seen.add(name);
-        const child = memberOf(node, name);
-        if (child === undefined) {
-            throw unimplementedKey(label, path);
+        return first;
+    }
+    /** The schemas checked at one place when `schema` is: it, its `$ref`, its allOf and its if branch. */
+    applied(doc, schema, value) {
+        const held = [[doc, schema]];
+        if (typeof schema["$ref"] === "string") {
+            const [target, referenced] = this.resolve(doc, schema["$ref"]);
+            held.push(...this.applied(target, referenced, value));
         }
-        skipSpace(cursor);
-        if (cursor.text.charCodeAt(cursor.at) !== 0x3a) {
-            throw malformed(label, path, "a member name is followed by a colon");
+        for (const each of listOf(schema, "allOf")) {
+            held.push(...this.applied(doc, each, value));
+        }
+        if (isRecord(schema["if"])) {
+            const branch = this.matches(doc, schema["if"], value, "") ? schema["then"] : schema["else"];
+            if (isRecord(branch)) {
+                held.push(...this.applied(doc, branch, value));
+            }
         }
-        cursor.at += 1;
-        walkValue(cursor, path, child, label);
+        return held;
+    }
+    /** The schemas `schema` checks the member or the entry `segment` names in `value` with. */
+    member(doc, schema, value, segment) {
+        if (Array.isArray(value)) {
+            return isRecord(schema["items"]) ? [[doc, schema["items"]]] : [];
+        }
+        const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+        const declared = declaredMember(properties, segment);
+        if (isRecord(declared)) {
+            return [[doc, declared]];
+        }
+        const additional = schema["additionalProperties"];
+        return isRecord(additional) ? [[doc, additional]] : [];
     }
 }
-function walkArray(cursor, at, node, label) {
-    const entry = node.kind === "list" ? { kind: "section", members: node.members ?? {} } : leaf;
-    let index = 0;
-    for (;;) {
-        skipSpace(cursor);
-        const ch = cursor.text.charCodeAt(cursor.at);
-        if (ch === 0x5d) {
-            cursor.at += 1;
-            return;
+/** The alternative a value matching none of them was written for, or none where none or two remain. */
+function closest(alternatives, value) {
+    const typed = alternatives.filter((each) => {
+        const types = typesOf(each);
+        return types.length === 0 || types.some((one) => hasType(value, one));
+    });
+    if (typed.length === 1 || !isRecord(value)) {
+        return typed.length === 1 ? typed[0] : undefined;
+    }
+    let best = [];
+    let most = -1;
+    let fewest = 0;
+    for (const alternative of typed) {
+        const properties = isRecord(alternative["properties"]) ? alternative["properties"] : {};
+        const named = Object.keys(value).filter((name) => Object.hasOwn(properties, name)).length;
+        const declared = Object.keys(properties).length;
+        if (named > most || (named === most && declared < fewest)) {
+            [best, most, fewest] = [[alternative], named, declared];
         }
-        if (ch === 0x2c) {
-            cursor.at += 1;
-            continue;
+        else if (named === most && declared === fewest) {
+            best.push(alternative);
         }
-        walkValue(cursor, `${at}[${index}]`, entry, label);
-        index += 1;
     }
+    return best.length === 1 ? best[0] : undefined;
 }
 /**
- * Walks one document's text against the closed key list, refusing a member the
- * key list does not declare and a member one object writes twice, each naming its
- * dotted path. The document is already known to parse.
+ * A validator over one set of schema documents, each named as a `$ref` names it, rooted
+ * at one of them: what it refuses in a value, none for an instance.
  */
-export function checkDocument(text, node, label) {
-    const cursor = { text, at: 0 };
-    walkValue(cursor, "", node, label);
+export function schemaRefusals(documents, root) {
+    const checker = new Checker(documents);
+    const top = documents[root];
+    if (top === undefined) {
+        throw new Error(`the schema set holds no document ${root}`);
+    }
+    return (value) => {
+        const found = [];
+        checker.check(root, top, value, "", found);
+        return found;
+    };
 }
 /**
- * The flag document, whose keys are dotted setting paths, rewritten as the nested
- * object the closed key list declares, so one decoder reads every source. A key
- * naming no setting is refused.
+ * The refusal of `value` a reader fixes first under one schema, none for an instance. A
+ * `$ref` the schema holds names a place in the schema itself.
  */
-export function nestFlags(flat, label) {
-    const nested = {};
-    for (const path of Object.keys(flat).sort()) {
-        if (!declaresSetting(path)) {
-            throw unimplementedKey(label, path);
-        }
-        const segments = path.split(".");
-        let into = nested;
-        for (const segment of segments.slice(0, -1)) {
-            const child = into[segment] ?? {};
-            if (typeof child !== "object" || Array.isArray(child)) {
-                throw malformed(label, path, `the flag document sets ${JSON.stringify(segment)} twice`);
-            }
-            into[segment] = child;
-            into = child;
-        }
-        const last = segments[segments.length - 1] ?? "";
-        into[last] = flat[path];
-    }
-    return nested;
+export function firstRefusal(schema, value) {
+    return new Checker({ "": schema }).first("", schema, value, "");
 }