@maroonedog/luq 2.4.4 → 2.6.0

package/README.md

@@ -42,6 +42,7 @@ compile error, not a rule that quietly never fires.
 | Descending into a built-in (`"when.getTime"` on a `Date`) | compile error |
 | A method that does not exist inside an element sub-chain | compile error |
 | A JSON Schema keyword bound to a chain method that does not exist | compile error |
+| A JSON Schema document declaring 2019-09 or 2020-12 | throws when the validator is built, rather than being read as Draft-07 |
 | A documented example drifting from the API | fails CI |
 
 That matters most when the code calling this library is generated rather than
@@ -50,10 +51,16 @@ an array wildcard gets a red squiggle, not a validator that passes everything.
 
 Two consequences worth knowing before you read further:
 
-- **Adoption is a patch, not a migration.** A path you did not declare is not
+- **Adoption is a patch, and so is removal.** A path you did not declare is not
   validated, not required, and not read, so a partly-covered type is a normal
   state rather than a half-finished one. There is nothing global to migrate: no
-  registry, no plugin installation, no shared configuration object.
+  registry, no plugin installation, no shared configuration object. Leaving is
+  the same size of change in the other direction — your types were never
+  authored here, so there is no generated file to delete and no inferred type to
+  replace by hand, and a consumer that takes a [Standard
+  Schema](https://luq.dev/standard-schema) does not change when you hand it a
+  different value. The rules themselves you would rewrite; that part is real,
+  and it is the same work whichever way you go.
 - **Every rule you can call is a plugin you imported by name**, so the bundle
   contains what you used and nothing else — an unimported plugin's method does
   not even typecheck. What each configuration costs is measured on every build:
@@ -95,7 +102,9 @@ somewhere.
 npm install @maroonedog/luq
 ```
 
-Zero runtime dependencies. TypeScript 5.0 or later.
+Zero runtime dependencies. TypeScript 5.0 or later. Your `tsconfig.json` does
+not need `strict` for any of the compile errors above, and they are checked with
+it on as well.
 
 ## The whole API
 
@@ -128,17 +137,58 @@ const result = orderValidator.validate({ reference: "ab", quantity: 0 });
 if (!result.valid) {
   for (const issue of result.issues) {
     // issue.path  "reference"   — where, with array indices filled in
-    // issue.code  "stringMin"   — which rule, stable across messages
+    // issue.code  "stringMin"   — which rule; the vocabulary is pinned
     // issue.message             — the text, overridable per call
     // issue.severity "error"    — only "error" makes the value invalid
   }
 }
 ```
 
+`issue.code` is the machine-readable half: a plugin's own name by default,
+overridden per rule with `{ code }`. The set is not a convention. The codes the
+library reports are enumerated in `config/issue-code.lock.json`, derived from
+the source by `npm run generate:issue-codes` and checked by
+`npm run check:issue-code-lock`, so renaming one is a diff in a committed file
+and a deliberate act rather than a silent break. The lock records who reports
+each code, because some codes are shared on purpose — a missing root and a
+missing field both report `required`. Codes a gate carries (`skip`,
+`validateIf`) sit in a separate list: they are accepted from a caller but no
+issue can ever carry one.
+
 `.v(path, chain)` declares rules for one field. A path you do not declare is
 not validated, not required and not read, so covering a type partly is a normal
 state rather than a half-finished one.
 
+### `.strict()` — when you want the whole type covered
+
+Partial cover is the default, so nothing tells you a field was forgotten. Add
+`.strict()` before `.build()` and the compiler does: it asserts every leaf path
+of your type has been declared, and if one is missing the returned object has
+no `build()` and names what is missing.
+
+```ts
+import { Builder } from "@maroonedog/luq";
+import { requiredPlugin } from "@maroonedog/luq/plugins/required";
+
+interface Pair {
+  readonly left: string;
+  readonly right: string;
+}
+
+export const pairs = Builder()
+  .use(requiredPlugin)
+  .for<Pair>()
+  .v("left", (b) => b.string.required())
+  .v("right", (b) => b.string.required())
+  .strict() //  drop either .v() above and this line stops compiling
+  .build();
+```
+
+It has no runtime effect and rejects no extra property at run time — it is a
+statement about your declarations, not about the data. For refusing unknown
+keys in the value, see
+[objectAdditionalProperties](https://luq.dev/plugins).
+
 ### What a built validator gives you
 
 ```ts
@@ -257,7 +307,7 @@ const forStringMin = PLUGIN_MANIFEST.filter((entry) =>
 | [Getting started](https://luq.dev/docs/getting-started) | the builder, defaults, `normalize`, reading a result |
 | [Core concepts](https://luq.dev/docs/core-concepts) | field paths, slots, presence, transforms |
 | [Plugins](https://luq.dev/plugins) | every subpath, symbol, chain method and slot |
-| [JSON Schema](https://luq.dev/json-schema) | reading a document in, writing one back out, measured Draft-07 conformance |
+| [JSON Schema](https://luq.dev/json-schema) | reading a Draft-07 document in, writing one back out, measured conformance, and why a newer-dialect document is refused |
 | [Standard Schema](https://luq.dev/standard-schema) | tRPC, TanStack Form, Hono, react-hook-form — and what does not cross that boundary |
 | [Benchmarks](https://luq.dev/benchmarks) | bundle size and throughput, with the method |
 | [Luq or zod?](https://luq.dev/luq-or-zod) | when schema-first is the better answer |
@@ -273,6 +323,8 @@ Breaking changes happen in a major and nowhere else, an API being removed is
 deprecated one major ahead, and each major ships with the codemod needed to
 cross it.
 
+- **[CHANGELOG.md](https://github.com/maroonedog/luq/blob/master/CHANGELOG.md)** — every released version, what a caller
+  sees change in each, and which ones need reading before you take them
 - **[CONTRIBUTING.md](https://github.com/maroonedog/luq/blob/master/CONTRIBUTING.md)** — `npm run verify` is the whole
   contract; the gates and what each one refuses
 - **[SECURITY.md](https://github.com/maroonedog/luq/blob/master/SECURITY.md)** — reporting, zero runtime dependencies, the
@@ -282,11 +334,13 @@ cross it.
 
 ## About the "universal platform" goal
 
-1.x described a `.luq` DSL that would generate validators for other languages,
-against dated milestones. Those dates have passed and none of it shipped, so the
-plan has been withdrawn rather than moved: no part of it is in this package, and
-this release makes no claim about when any of it will exist. What is in the box
-is the TypeScript validation library described above.
+The first published line — `0.1.0-alpha` through `0.1.2-alpha`, which the
+migration guide and the docs site both call "1.x" although no `1.x` was ever
+published — described a `.luq` DSL that would generate validators for other
+languages, against dated milestones. Those dates have passed and none of it
+shipped, so the plan has been withdrawn rather than moved: no part of it is in
+this package, and this release makes no claim about when any of it will exist.
+What is in the box is the TypeScript validation library described above.
 
 ## License
 

package/dist/chain/slot-type-guard.js

@@ -3,16 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.slotTypeGuard = slotTypeGuard;
 const types_1 = require("../types");
 const create_rule_1 = require("../plugin-kit/create-rule");
+/**
+ * Each code is SPELLED here rather than interpolated from the slot name.
+ *
+ * `${slot}Type` produced the same six strings, and produced them nowhere a
+ * reader could find them: config/issue-code.lock.json enumerates every code
+ * the library can report, and a code that only exists once a template has been
+ * evaluated cannot be enumerated, so these six were missing from the published
+ * vocabulary while being among the most commonly reported codes there are.
+ */
 const SLOT_TYPES = Object.freeze({
-    string: { accepts: types_1.isString, noun: "a string" },
-    number: { accepts: types_1.isNumber, noun: "a number" },
+    string: { accepts: types_1.isString, code: "stringType", noun: "a string" },
+    number: { accepts: types_1.isNumber, code: "numberType", noun: "a number" },
     boolean: {
         accepts: (value) => typeof value === "boolean",
+        code: "booleanType",
         noun: "a boolean",
     },
-    date: { accepts: (value) => value instanceof Date, noun: "a Date" },
-    array: { accepts: types_1.isArray, noun: "an array" },
-    object: { accepts: types_1.isPlainObject, noun: "an object" },
+    date: {
+        accepts: (value) => value instanceof Date,
+        code: "dateType",
+        noun: "a Date",
+    },
+    array: { accepts: types_1.isArray, code: "arrayType", noun: "an array" },
+    object: { accepts: types_1.isPlainObject, code: "objectType", noun: "an object" },
 });
 /**
  * The rule `b.<slot>` starts its chain with, or null for a slot that claims
@@ -26,7 +40,7 @@ function slotTypeGuard(slot, severity) {
     if (slotType === undefined)
         return null;
     return (0, create_rule_1.check)({
-        code: `${slot}Type`,
+        code: slotType.code,
         severity,
         run: (value) => value === undefined || value === null || slotType.accepts(value)
             ? types_1.PASS

package/dist/chain/slot-type-guard.mjs

@@ -1,15 +1,29 @@
 import { PASS, fail, isArray, isNumber, isPlainObject, isString, } from "../types/index.mjs";
 import { check } from "../plugin-kit/create-rule.mjs";
+/**
+ * Each code is SPELLED here rather than interpolated from the slot name.
+ *
+ * `${slot}Type` produced the same six strings, and produced them nowhere a
+ * reader could find them: config/issue-code.lock.json enumerates every code
+ * the library can report, and a code that only exists once a template has been
+ * evaluated cannot be enumerated, so these six were missing from the published
+ * vocabulary while being among the most commonly reported codes there are.
+ */
 const SLOT_TYPES = Object.freeze({
-    string: { accepts: isString, noun: "a string" },
-    number: { accepts: isNumber, noun: "a number" },
+    string: { accepts: isString, code: "stringType", noun: "a string" },
+    number: { accepts: isNumber, code: "numberType", noun: "a number" },
     boolean: {
         accepts: (value) => typeof value === "boolean",
+        code: "booleanType",
         noun: "a boolean",
     },
-    date: { accepts: (value) => value instanceof Date, noun: "a Date" },
-    array: { accepts: isArray, noun: "an array" },
-    object: { accepts: isPlainObject, noun: "an object" },
+    date: {
+        accepts: (value) => value instanceof Date,
+        code: "dateType",
+        noun: "a Date",
+    },
+    array: { accepts: isArray, code: "arrayType", noun: "an array" },
+    object: { accepts: isPlainObject, code: "objectType", noun: "an object" },
 });
 /**
  * The rule `b.<slot>` starts its chain with, or null for a slot that claims
@@ -23,7 +37,7 @@ export function slotTypeGuard(slot, severity) {
     if (slotType === undefined)
         return null;
     return check({
-        code: `${slot}Type`,
+        code: slotType.code,
         severity,
         run: (value) => value === undefined || value === null || slotType.accepts(value)
             ? PASS

package/dist/compile/resolve-presence.js

@@ -38,13 +38,43 @@ function countRestrictions(rule) {
         (rule.allowNull ? 0 : 1) +
         (rule.emptyStringIsMissing ? 1 : 0));
 }
+/**
+ * Which of two equally restrictive rules is reported, decided on WHAT each one
+ * forbids: undefined first, then null, then the empty string.
+ *
+ * The order is declared here rather than falling out of something else. It
+ * runs from the broadest absence to the narrowest — a field that is not there
+ * at all, a field that is there holding null, a field holding "" — so the
+ * identity a caller sees names the largest thing that was missing.
+ *
+ * Nothing in this comparison reads a code. A code is a published name, pinned
+ * in config/issue-code.lock.json, and re-spelling one must not move which rule
+ * a failure is reported under; comparing the two codes made exactly that
+ * happen, silently, from a one-word rename.
+ *
+ * Two rules forbidding the identical three things are indistinguishable to
+ * every reader of the policy, so neither outranks the other and the one
+ * declared first stays. That is the only case where the order the methods were
+ * typed in is observable at all.
+ */
+function outranksOnRestriction(rule, incumbent) {
+    if (rule.allowUndefined !== incumbent.allowUndefined) {
+        return !rule.allowUndefined;
+    }
+    if (rule.allowNull !== incumbent.allowNull)
+        return !rule.allowNull;
+    if (rule.emptyStringIsMissing !== incumbent.emptyStringIsMissing) {
+        return rule.emptyStringIsMissing;
+    }
+    return false;
+}
 /**
  * The identity a failure is reported under: the rule that forbids the most,
- * ties broken by the lexicographically smaller code.
+ * ties broken by which absence it forbids.
  *
- * Tie-breaking on the CODE rather than on declaration order is what keeps the
- * whole policy — not merely its three flags — independent of the order the
- * rules arrived in. `.optional().nullable()` and `.nullable().optional()` are
+ * Both halves of the decision read only the three presence flags, so the whole
+ * policy — not merely its flags — is independent of the order the rules
+ * arrived in. `.optional().nullable()` and `.nullable().optional()` are
  * deep-equal, which is the property the tests assert.
  */
 function selectStrictestPresence(rules) {
@@ -55,7 +85,8 @@ function selectStrictestPresence(rules) {
             continue;
         }
         const difference = countRestrictions(rule) - countRestrictions(strictest);
-        if (difference > 0 || (difference === 0 && rule.code < strictest.code)) {
+        if (difference > 0 ||
+            (difference === 0 && outranksOnRestriction(rule, strictest))) {
             strictest = rule;
         }
     }

package/dist/compile/resolve-presence.mjs

@@ -34,13 +34,43 @@ function countRestrictions(rule) {
         (rule.allowNull ? 0 : 1) +
         (rule.emptyStringIsMissing ? 1 : 0));
 }
+/**
+ * Which of two equally restrictive rules is reported, decided on WHAT each one
+ * forbids: undefined first, then null, then the empty string.
+ *
+ * The order is declared here rather than falling out of something else. It
+ * runs from the broadest absence to the narrowest — a field that is not there
+ * at all, a field that is there holding null, a field holding "" — so the
+ * identity a caller sees names the largest thing that was missing.
+ *
+ * Nothing in this comparison reads a code. A code is a published name, pinned
+ * in config/issue-code.lock.json, and re-spelling one must not move which rule
+ * a failure is reported under; comparing the two codes made exactly that
+ * happen, silently, from a one-word rename.
+ *
+ * Two rules forbidding the identical three things are indistinguishable to
+ * every reader of the policy, so neither outranks the other and the one
+ * declared first stays. That is the only case where the order the methods were
+ * typed in is observable at all.
+ */
+function outranksOnRestriction(rule, incumbent) {
+    if (rule.allowUndefined !== incumbent.allowUndefined) {
+        return !rule.allowUndefined;
+    }
+    if (rule.allowNull !== incumbent.allowNull)
+        return !rule.allowNull;
+    if (rule.emptyStringIsMissing !== incumbent.emptyStringIsMissing) {
+        return rule.emptyStringIsMissing;
+    }
+    return false;
+}
 /**
  * The identity a failure is reported under: the rule that forbids the most,
- * ties broken by the lexicographically smaller code.
+ * ties broken by which absence it forbids.
  *
- * Tie-breaking on the CODE rather than on declaration order is what keeps the
- * whole policy — not merely its three flags — independent of the order the
- * rules arrived in. `.optional().nullable()` and `.nullable().optional()` are
+ * Both halves of the decision read only the three presence flags, so the whole
+ * policy — not merely its flags — is independent of the order the rules
+ * arrived in. `.optional().nullable()` and `.nullable().optional()` are
  * deep-equal, which is the property the tests assert.
  */
 function selectStrictestPresence(rules) {
@@ -51,7 +81,8 @@ function selectStrictestPresence(rules) {
             continue;
         }
         const difference = countRestrictions(rule) - countRestrictions(strictest);
-        if (difference > 0 || (difference === 0 && rule.code < strictest.code)) {
+        if (difference > 0 ||
+            (difference === 0 && outranksOnRestriction(rule, strictest))) {
             strictest = rule;
         }
     }

package/dist/json-schema/array-keyword-guards.d.ts

@@ -0,0 +1,31 @@
+import type { Draft07Schema, Draft07SchemaObject } from "./draft07.types";
+/** The two shapes §9.3.1 permits `items` to take. */
+export type ItemsValue = Draft07Schema | readonly Draft07Schema[];
+/**
+ * Reads `items` after checking it against the meta-schema: the keyword's own
+ * value, or undefined when the keyword is absent, and a refusal when it is
+ * neither of the two forms §9.3.1 defines.
+ */
+export declare function readCheckedItems(schema: Draft07SchemaObject): ItemsValue | undefined;
+/**
+ * Reads `additionalItems` after checking it is a single schema: the keyword's
+ * own value, or undefined when the keyword is absent, and a refusal for
+ * anything §4.4 does not call a schema.
+ *
+ * It is read only where §6.4.2 gives the keyword effect, which is beside the
+ * tuple form of `items`; beside the single form the draft ignores it, no rest
+ * branch is built and this reader is never reached.
+ */
+export declare function readCheckedAdditionalItems(schema: Draft07SchemaObject): Draft07Schema | undefined;
+/**
+ * Reads `contains` after checking it is a single schema: the keyword's own
+ * value, or undefined when the keyword is absent, and a refusal for anything
+ * §4.4 does not call a schema. Unlike `items`, `contains` has no array form —
+ * a tuple there is a malformed value, not a second reading.
+ */
+export declare function readCheckedContains(schema: Draft07SchemaObject): Draft07Schema | undefined;
+/**
+ * Reads `uniqueItems` after checking it is a boolean: the keyword's own value,
+ * or undefined when the keyword is absent, and a refusal for anything else.
+ */
+export declare function readCheckedUniqueItems(schema: Draft07SchemaObject): boolean | undefined;

package/dist/json-schema/array-keyword-guards.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCheckedItems = readCheckedItems;
+exports.readCheckedAdditionalItems = readCheckedAdditionalItems;
+exports.readCheckedContains = readCheckedContains;
+exports.readCheckedUniqueItems = readCheckedUniqueItems;
+// ===========================================================================
+// L8  src/json-schema/array-keyword-guards.ts — the meta-schema checks for
+// `items`, `additionalItems`, `contains` and `uniqueItems`, read by
+// flatten-array-schema.ts.
+//
+// Every one of these keywords decides whether a rule EXISTS, and each had a
+// route where a value the meta-schema forbids produced no rule at all rather
+// than an error. `items: 5` is not a schema, but the sub-schema walker takes it
+// anyway and iterates its keys; a number has none, so the walker yields zero
+// rules and every element passes — the document asked for a constraint and the
+// built validator carries an always-true one in its place. `additionalItems: 5`
+// takes that same route for the rest branch, so every element past the tuple
+// goes unchecked. `contains: 5` is the same bug wearing a disguise: an
+// always-true element branch matches the FIRST element, so the existence
+// requirement collapses into "the array is non-empty" — the empty array is
+// still refused, and that lawful-looking verdict is what makes the loss of the
+// real constraint easy to miss. `uniqueItems` is honoured only on a strict
+// `=== true`, so `uniqueItems: "yes"`, the shape a form encoding or a loose
+// YAML loader produces, drops to nothing the same way.
+//
+// A validator that quietly enforces LESS than its document says cannot be
+// detected downstream: it answers "valid" for exactly the inputs the schema
+// meant to refuse, and nothing in the result says a constraint went missing.
+// Build time is therefore the only place a caller can still act, so these
+// read the value and refuse it there.
+//
+// What must survive the refusal, because Draft-07 defines it: `items` has TWO
+// legal forms — one schema for every element, or an ARRAY of schemas where
+// position i constrains element i (§9.3.1) — `additionalItems` and `contains`
+// take the boolean form of a schema as readily as the object form (§4.4), and
+// `uniqueItems: false` is a lawful no-op (§6.4.3), so only a NON-boolean is
+// refused.
+// ===========================================================================
+const types_1 = require("../types");
+const draft07_types_1 = require("./draft07.types");
+const malformed_schema_error_1 = require("./malformed-schema-error");
+const ITEMS_REASON = "the value must be a schema or an array of schemas";
+const UNIQUE_ITEMS_REASON = "the value must be a boolean";
+/**
+ * Reads `items` after checking it against the meta-schema: the keyword's own
+ * value, or undefined when the keyword is absent, and a refusal when it is
+ * neither of the two forms §9.3.1 defines.
+ */
+function readCheckedItems(schema) {
+    const items = schema.items;
+    if (items === undefined)
+        return undefined;
+    if ((0, types_1.isArray)(items))
+        return checkTuplePositions(items);
+    if (!(0, draft07_types_1.isDraft07Schema)(items)) {
+        throw new malformed_schema_error_1.MalformedSchemaError("items", ITEMS_REASON, items);
+    }
+    return items;
+}
+/**
+ * Every position of the tuple form is a schema in its own right, so a bad one
+ * names its index: with the whole array rendered instead, a caller holding a
+ * long tuple is told only that something in it is wrong.
+ */
+function checkTuplePositions(positions) {
+    for (let index = 0; index < positions.length; index += 1) {
+        const position = positions[index];
+        if ((0, draft07_types_1.isDraft07Schema)(position))
+            continue;
+        throw new malformed_schema_error_1.MalformedSchemaError("items", `position ${String(index)} of the array form ${malformed_schema_error_1.SCHEMA_FORMS}`, position);
+    }
+    return positions;
+}
+/**
+ * Reads `additionalItems` after checking it is a single schema: the keyword's
+ * own value, or undefined when the keyword is absent, and a refusal for
+ * anything §4.4 does not call a schema.
+ *
+ * It is read only where §6.4.2 gives the keyword effect, which is beside the
+ * tuple form of `items`; beside the single form the draft ignores it, no rest
+ * branch is built and this reader is never reached.
+ */
+function readCheckedAdditionalItems(schema) {
+    const additionalItems = schema.additionalItems;
+    if (additionalItems === undefined)
+        return undefined;
+    if (!(0, draft07_types_1.isDraft07Schema)(additionalItems)) {
+        throw new malformed_schema_error_1.MalformedSchemaError("additionalItems", `the value ${malformed_schema_error_1.SCHEMA_FORMS}`, additionalItems);
+    }
+    return additionalItems;
+}
+/**
+ * Reads `contains` after checking it is a single schema: the keyword's own
+ * value, or undefined when the keyword is absent, and a refusal for anything
+ * §4.4 does not call a schema. Unlike `items`, `contains` has no array form —
+ * a tuple there is a malformed value, not a second reading.
+ */
+function readCheckedContains(schema) {
+    const contains = schema.contains;
+    if (contains === undefined)
+        return undefined;
+    if (!(0, draft07_types_1.isDraft07Schema)(contains)) {
+        throw new malformed_schema_error_1.MalformedSchemaError("contains", `the value ${malformed_schema_error_1.SCHEMA_FORMS}`, contains);
+    }
+    return contains;
+}
+/**
+ * Reads `uniqueItems` after checking it is a boolean: the keyword's own value,
+ * or undefined when the keyword is absent, and a refusal for anything else.
+ */
+function readCheckedUniqueItems(schema) {
+    const uniqueItems = schema.uniqueItems;
+    if (uniqueItems === undefined)
+        return undefined;
+    if (typeof uniqueItems !== "boolean") {
+        throw new malformed_schema_error_1.MalformedSchemaError("uniqueItems", UNIQUE_ITEMS_REASON, uniqueItems);
+    }
+    return uniqueItems;
+}

package/dist/json-schema/array-keyword-guards.mjs

@@ -0,0 +1,114 @@
+// ===========================================================================
+// L8  src/json-schema/array-keyword-guards.ts — the meta-schema checks for
+// `items`, `additionalItems`, `contains` and `uniqueItems`, read by
+// flatten-array-schema.ts.
+//
+// Every one of these keywords decides whether a rule EXISTS, and each had a
+// route where a value the meta-schema forbids produced no rule at all rather
+// than an error. `items: 5` is not a schema, but the sub-schema walker takes it
+// anyway and iterates its keys; a number has none, so the walker yields zero
+// rules and every element passes — the document asked for a constraint and the
+// built validator carries an always-true one in its place. `additionalItems: 5`
+// takes that same route for the rest branch, so every element past the tuple
+// goes unchecked. `contains: 5` is the same bug wearing a disguise: an
+// always-true element branch matches the FIRST element, so the existence
+// requirement collapses into "the array is non-empty" — the empty array is
+// still refused, and that lawful-looking verdict is what makes the loss of the
+// real constraint easy to miss. `uniqueItems` is honoured only on a strict
+// `=== true`, so `uniqueItems: "yes"`, the shape a form encoding or a loose
+// YAML loader produces, drops to nothing the same way.
+//
+// A validator that quietly enforces LESS than its document says cannot be
+// detected downstream: it answers "valid" for exactly the inputs the schema
+// meant to refuse, and nothing in the result says a constraint went missing.
+// Build time is therefore the only place a caller can still act, so these
+// read the value and refuse it there.
+//
+// What must survive the refusal, because Draft-07 defines it: `items` has TWO
+// legal forms — one schema for every element, or an ARRAY of schemas where
+// position i constrains element i (§9.3.1) — `additionalItems` and `contains`
+// take the boolean form of a schema as readily as the object form (§4.4), and
+// `uniqueItems: false` is a lawful no-op (§6.4.3), so only a NON-boolean is
+// refused.
+// ===========================================================================
+import { isArray } from "../types/index.mjs";
+import { isDraft07Schema } from "./draft07.types.mjs";
+import { MalformedSchemaError, SCHEMA_FORMS } from "./malformed-schema-error.mjs";
+const ITEMS_REASON = "the value must be a schema or an array of schemas";
+const UNIQUE_ITEMS_REASON = "the value must be a boolean";
+/**
+ * Reads `items` after checking it against the meta-schema: the keyword's own
+ * value, or undefined when the keyword is absent, and a refusal when it is
+ * neither of the two forms §9.3.1 defines.
+ */
+export function readCheckedItems(schema) {
+    const items = schema.items;
+    if (items === undefined)
+        return undefined;
+    if (isArray(items))
+        return checkTuplePositions(items);
+    if (!isDraft07Schema(items)) {
+        throw new MalformedSchemaError("items", ITEMS_REASON, items);
+    }
+    return items;
+}
+/**
+ * Every position of the tuple form is a schema in its own right, so a bad one
+ * names its index: with the whole array rendered instead, a caller holding a
+ * long tuple is told only that something in it is wrong.
+ */
+function checkTuplePositions(positions) {
+    for (let index = 0; index < positions.length; index += 1) {
+        const position = positions[index];
+        if (isDraft07Schema(position))
+            continue;
+        throw new MalformedSchemaError("items", `position ${String(index)} of the array form ${SCHEMA_FORMS}`, position);
+    }
+    return positions;
+}
+/**
+ * Reads `additionalItems` after checking it is a single schema: the keyword's
+ * own value, or undefined when the keyword is absent, and a refusal for
+ * anything §4.4 does not call a schema.
+ *
+ * It is read only where §6.4.2 gives the keyword effect, which is beside the
+ * tuple form of `items`; beside the single form the draft ignores it, no rest
+ * branch is built and this reader is never reached.
+ */
+export function readCheckedAdditionalItems(schema) {
+    const additionalItems = schema.additionalItems;
+    if (additionalItems === undefined)
+        return undefined;
+    if (!isDraft07Schema(additionalItems)) {
+        throw new MalformedSchemaError("additionalItems", `the value ${SCHEMA_FORMS}`, additionalItems);
+    }
+    return additionalItems;
+}
+/**
+ * Reads `contains` after checking it is a single schema: the keyword's own
+ * value, or undefined when the keyword is absent, and a refusal for anything
+ * §4.4 does not call a schema. Unlike `items`, `contains` has no array form —
+ * a tuple there is a malformed value, not a second reading.
+ */
+export function readCheckedContains(schema) {
+    const contains = schema.contains;
+    if (contains === undefined)
+        return undefined;
+    if (!isDraft07Schema(contains)) {
+        throw new MalformedSchemaError("contains", `the value ${SCHEMA_FORMS}`, contains);
+    }
+    return contains;
+}
+/**
+ * Reads `uniqueItems` after checking it is a boolean: the keyword's own value,
+ * or undefined when the keyword is absent, and a refusal for anything else.
+ */
+export function readCheckedUniqueItems(schema) {
+    const uniqueItems = schema.uniqueItems;
+    if (uniqueItems === undefined)
+        return undefined;
+    if (typeof uniqueItems !== "boolean") {
+        throw new MalformedSchemaError("uniqueItems", UNIQUE_ITEMS_REASON, uniqueItems);
+    }
+    return uniqueItems;
+}