@crewhaus/tool-schema 0.7.0 → 0.8.0

package/dist/lib/assert.js

@@ -8,6 +8,7 @@
  * only compares.
  */
 import { checkFormat, isFormatName } from "./formats";
+import { testPatternSync } from "./regex-answers";
 import { deepEqual, getPath, isPlainObject, matchesType, preview, typeOf, } from "./value";
 /** Every comparison {@link runChecks} understands. */
 export const ASSERT_OPS = [
@@ -77,22 +78,42 @@ function compareLength(actual, expected, ok, describe) {
         ? { ok: true, reason: "" }
         : { ok: false, reason: describe(length, expected) };
 }
-function matchRegex(actual, expected, flags, want) {
+/**
+ * `matches` / `notMatches`. The pattern is the caller's, so it is never run
+ * here: the answer comes from `regex` (resolved in the worker by the tool
+ * that called), or, for a caller with none, from the bounded fallback on
+ * this thread. A pattern the screen refuses fails the check, as an invalid
+ * one always has; one that could not be run to an answer is undetermined,
+ * never "does not match" (and so never a pass for `notMatches`).
+ */
+function matchRegex(actual, expected, flags, want, regex) {
     if (typeof actual !== "string") {
         return { ok: false, reason: `matches needs a string, found ${typeOf(actual)}` };
     }
     if (typeof expected !== "string") {
         return { ok: false, reason: "the check's expected value must be a regex source string" };
     }
-    let re;
-    try {
-        re = new RegExp(expected, flags);
+    const answer = regex === undefined
+        ? testPatternSync(expected, flags, actual)
+        : regex.lookup(expected, flags, actual);
+    if (answer === undefined) {
+        return {
+            ok: false,
+            undetermined: true,
+            reason: `could not evaluate /${expected}/${flags}: its answer has not been worked out yet`,
+        };
     }
-    catch (err) {
-        return { ok: false, reason: `invalid regex /${expected}/${flags}: ${err.message}` };
+    if (typeof answer !== "boolean") {
+        if ("refused" in answer) {
+            return { ok: false, reason: `invalid regex /${expected}/${flags}: ${answer.refused}` };
+        }
+        return {
+            ok: false,
+            undetermined: true,
+            reason: `could not evaluate /${expected}/${flags}: ${answer.undetermined}`,
+        };
     }
-    const matched = re.test(actual);
-    if (matched === want)
+    if (answer === want)
         return { ok: true, reason: "" };
     return {
         ok: false,
@@ -101,7 +122,37 @@ function matchRegex(actual, expected, flags, want) {
             : `${preview(actual, 60)} matches /${expected}/${flags} but must not`,
     };
 }
-function evaluate(check, actual, found) {
+/**
+ * Ask `answers` about every pattern `checks` will test against `value`, so
+ * one {@link RegexAnswers.resolve} settles them all before
+ * {@link runChecks} reads them. A caller evaluating several check lists
+ * against one value (a table's rows, a router's arms) asks for every list
+ * first, then resolves once.
+ */
+export function askCheckPatterns(value, checks, answers) {
+    for (const check of checks) {
+        if (check.op !== "matches" && check.op !== "notMatches")
+            continue;
+        if (typeof check.expected !== "string")
+            continue;
+        let actual = value;
+        const path = check.path ?? "";
+        if (path !== "") {
+            try {
+                const resolution = getPath(value, path);
+                if (!resolution.found)
+                    continue;
+                actual = resolution.value;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (typeof actual === "string")
+            answers.lookup(check.expected, check.flags ?? "", actual);
+    }
+}
+function evaluate(check, actual, found, regex) {
     const expected = check.expected;
     switch (check.op) {
         case "exists":
@@ -156,9 +207,9 @@ function evaluate(check, actual, found) {
             };
         }
         case "matches":
-            return matchRegex(actual, expected, check.flags ?? "", true);
+            return matchRegex(actual, expected, check.flags ?? "", true, regex);
         case "notMatches":
-            return matchRegex(actual, expected, check.flags ?? "", false);
+            return matchRegex(actual, expected, check.flags ?? "", false, regex);
         case "startsWith":
         case "endsWith": {
             if (typeof actual !== "string" || typeof expected !== "string") {
@@ -256,8 +307,14 @@ function evaluate(check, actual, found) {
  * A malformed check (a bad regex, a non-numeric bound) fails that check with
  * an explanatory reason rather than throwing, so one typo cannot take down a
  * whole gate.
+ *
+ * `matches` and `notMatches` read their answers from `options.regex`, which
+ * the calling tool resolved in the worker (see {@link askCheckPatterns});
+ * without it they fall back to a bounded run on this thread. A check whose
+ * pattern could not be run to an answer is not ok and carries
+ * `undetermined: true`; its reason says so whatever `message` the check set.
  */
-export function runChecks(value, checks) {
+export function runChecks(value, checks, options = {}) {
     const results = checks.map((check, index) => {
         const path = check.path ?? "";
         let found = true;
@@ -291,7 +348,7 @@ export function runChecks(value, checks) {
                 reason: check.message ?? `the path "${path}" does not resolve`,
             };
         }
-        const verdict = evaluate(check, actual, found);
+        const verdict = evaluate(check, actual, found, options.regex);
         return {
             index,
             path,
@@ -299,7 +356,12 @@ export function runChecks(value, checks) {
             ok: verdict.ok,
             actual: found ? preview(actual, 80) : null,
             expected: check.expected === undefined ? null : preview(check.expected, 80),
-            reason: verdict.ok ? "" : (check.message ?? verdict.reason),
+            reason: verdict.ok
+                ? ""
+                : verdict.undetermined === true
+                    ? verdict.reason
+                    : (check.message ?? verdict.reason),
+            ...(verdict.undetermined === true ? { undetermined: true } : {}),
         };
     });
     const failures = results.filter((r) => !r.ok);
@@ -307,10 +369,29 @@ export function runChecks(value, checks) {
         ok: failures.length === 0,
         passed: results.length - failures.length,
         failed: failures.length,
+        undetermined: failures.filter((r) => r.undetermined === true).length,
         results,
         failures,
     };
 }
+/**
+ * What a check list says as a whole, three ways. Under `all`, a check that
+ * definitely failed decides it (`fail`); otherwise an undetermined one leaves
+ * it `undetermined`. Under `any`, a check that passed decides it (`pass`);
+ * otherwise an undetermined one leaves it `undetermined`. A router or a
+ * scorer that reads `report.ok` alone would take an undetermined check for a
+ * miss and fall through to the next arm or the default.
+ */
+export function checksVerdict(report, mode = "all") {
+    if (mode === "all") {
+        if (report.ok)
+            return "pass";
+        return report.failed > report.undetermined ? "fail" : "undetermined";
+    }
+    if (report.passed > 0)
+        return "pass";
+    return report.undetermined > 0 ? "undetermined" : "fail";
+}
 /**
  * Which of `paths` are present and non-empty in `value`, and which are not.
  * "Present" means the path resolves; "non-empty" applies

package/dist/lib/compare.js

@@ -51,6 +51,27 @@ function matchPattern(segments, pattern) {
     }
     return s === segments.length;
 }
+/**
+ * Note a path `ignorePaths` matched, once. A set answers "listed already?":
+ * searching the list made a value with many ignored paths quadratic in them.
+ */
+function noteIgnored(ctx, path) {
+    if (ctx.ignoredSeen.has(path))
+        return;
+    ctx.ignoredSeen.add(path);
+    ctx.ignored.push(path);
+}
+/**
+ * Note an array compared positionally because it was too long, once. As for
+ * `noteIgnored`, a set answers "listed already?": searching the list made a
+ * value with many long arrays quadratic in them.
+ */
+function noteOrderedFallback(ctx, path) {
+    if (ctx.orderedFallbacksSeen.has(path))
+        return;
+    ctx.orderedFallbacksSeen.add(path);
+    ctx.orderedFallbacks.push(path);
+}
 function record(ctx, diff) {
     if (ctx.differences.length >= ctx.opts.maxDifferences) {
         ctx.truncated = true;
@@ -73,15 +94,16 @@ function equalUnder(actual, expected, ctx, path) {
         differences: [],
         truncated: false,
         ignored: [],
+        ignoredSeen: new Set(),
         orderedFallbacks: [],
+        orderedFallbacksSeen: new Set(),
     };
     walk(actual, expected, path, probe);
     return probe.differences.length === 0;
 }
 function walk(actual, expected, path, ctx) {
     if (matchesAnyPattern(path, ctx.patterns)) {
-        if (!ctx.ignored.includes(path))
-            ctx.ignored.push(path);
+        noteIgnored(ctx, path);
         return;
     }
     const expectedType = typeOf(expected);
@@ -132,9 +154,8 @@ function walk(actual, expected, path, ctx) {
 }
 function compareArrays(actual, expected, path, ctx) {
     const tooLong = actual.length > UNORDERED_ARRAY_LIMIT || expected.length > UNORDERED_ARRAY_LIMIT;
-    if (ctx.opts.ignoreArrayOrder && tooLong && !ctx.orderedFallbacks.includes(path)) {
-        ctx.orderedFallbacks.push(path);
-    }
+    if (ctx.opts.ignoreArrayOrder && tooLong)
+        noteOrderedFallback(ctx, path);
     if (ctx.opts.ignoreArrayOrder && !tooLong) {
         compareArraysUnordered(actual, expected, path, ctx);
         return;
@@ -208,8 +229,7 @@ function compareObjects(actual, expected, path, ctx) {
         const childPath = joinPointer(path, key);
         if (!Object.hasOwn(actual, key)) {
             if (matchesAnyPattern(childPath, ctx.patterns)) {
-                if (!ctx.ignored.includes(childPath))
-                    ctx.ignored.push(childPath);
+                noteIgnored(ctx, childPath);
                 continue;
             }
             record(ctx, {
@@ -230,8 +250,7 @@ function compareObjects(actual, expected, path, ctx) {
             continue;
         const childPath = joinPointer(path, key);
         if (matchesAnyPattern(childPath, ctx.patterns)) {
-            if (!ctx.ignored.includes(childPath))
-                ctx.ignored.push(childPath);
+            noteIgnored(ctx, childPath);
             continue;
         }
         record(ctx, {
@@ -260,7 +279,9 @@ export function compareValues(actual, expected, options = {}) {
         differences: [],
         truncated: false,
         ignored: [],
+        ignoredSeen: new Set(),
         orderedFallbacks: [],
+        orderedFallbacksSeen: new Set(),
     };
     walk(actual, expected, "", ctx);
     return {

package/dist/lib/formats.d.ts

@@ -65,6 +65,19 @@ export declare function isDate(value: string): FormatResult;
  * seconds. An offset with minutes over 59 is rejected.
  */
 export declare function isTime(value: string): FormatResult;
+/**
+ * A date-time split at its separator: one character, then everything up to
+ * the first `T` or `t` after it, then a non-empty rest. `.` and the class
+ * both stop at a line break (`\n`, `\r`, U+2028, U+2029), so a value that
+ * holds one never splits.
+ *
+ * This was `/^(.+?)[Tt](.+)$/`, which splits the same way. Its lazy group
+ * tried every `T` of a long first line and ran `(.+)` from each to the line
+ * break that `$` cannot pass: quadratic in the line, on ordinary prose. A
+ * failed try now gives back only characters that cannot be a `T`, one step
+ * each.
+ */
+export declare const DATE_TIME_SPLIT: RegExp;
 /**
  * RFC 3339 `date-time`: a date, a `T` (or lowercase `t`) separator, and a
  * time with an offset. A space separator, as SQL writes it, is rejected —

package/dist/lib/formats.js

@@ -212,13 +212,26 @@ export function isTime(value) {
     }
     return OK;
 }
+/**
+ * A date-time split at its separator: one character, then everything up to
+ * the first `T` or `t` after it, then a non-empty rest. `.` and the class
+ * both stop at a line break (`\n`, `\r`, U+2028, U+2029), so a value that
+ * holds one never splits.
+ *
+ * This was `/^(.+?)[Tt](.+)$/`, which splits the same way. Its lazy group
+ * tried every `T` of a long first line and ran `(.+)` from each to the line
+ * break that `$` cannot pass: quadratic in the line, on ordinary prose. A
+ * failed try now gives back only characters that cannot be a `T`, one step
+ * each.
+ */
+export const DATE_TIME_SPLIT = /^(.[^Tt\n\r\u2028\u2029]*)[Tt](.+)$/;
 /**
  * RFC 3339 `date-time`: a date, a `T` (or lowercase `t`) separator, and a
  * time with an offset. A space separator, as SQL writes it, is rejected —
  * this is the strict interchange form.
  */
 export function isDateTime(value) {
-    const split = value.match(/^(.+?)[Tt](.+)$/);
+    const split = value.match(DATE_TIME_SPLIT);
     if (split === null)
         return bad('expected a "T" between the date and the time');
     const date = isDate(split[1] ?? "");

package/dist/lib/jsonschema.d.ts

@@ -1,3 +1,91 @@
+/**
+ * A JSON Schema Draft-07 validator, written out in full here so the package
+ * has no runtime dependency and so its behaviour is auditable in one file.
+ *
+ * ## What is enforced
+ *
+ * | Group | Keywords |
+ * |---|---|
+ * | any | `type`, `enum`, `const` |
+ * | number | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` |
+ * | string | `minLength`, `maxLength`, `pattern`, `format` (opt-in) |
+ * | array | `items` (schema or tuple), `additionalItems`, `contains`, `minItems`, `maxItems`, `uniqueItems` |
+ * | object | `properties`, `patternProperties`, `additionalProperties`, `propertyNames`, `required`, `minProperties`, `maxProperties` |
+ * | logic | `allOf`, `anyOf`, `oneOf`, `not`, `if`/`then`/`else` |
+ * | reference | `$ref` to a local JSON Pointer, including `#/$defs/...` and `#/definitions/...` |
+ *
+ * Boolean schemas (`true` accepts everything, `false` rejects everything) are
+ * supported wherever a schema is expected.
+ *
+ * ## What is NOT enforced
+ *
+ * - **Annotations**, which carry no constraint and are skipped silently:
+ *   `$id`, `$schema`, `$comment`, `title`, `description`, `default`,
+ *   `examples`, `readOnly`, `writeOnly`, `deprecated`, `contentMediaType`,
+ *   `contentEncoding`, `$defs`, `definitions`.
+ * - **`format`**, unless `assertFormat` is set. Draft-07 makes `format` an
+ *   annotation by default and this validator follows that; the opt-in uses
+ *   the checks in `./formats`, whose subsets are documented there.
+ * - **`dependencies` / `dependentRequired` / `dependentSchemas`**,
+ *   **`unevaluatedProperties` / `unevaluatedItems`**, the draft-04 boolean
+ *   form of `exclusiveMinimum`/`exclusiveMaximum`, and any other keyword not
+ *   in the table above. These are never silently dropped: every one
+ *   encountered is listed in the result's `unsupportedKeywords`, so a caller
+ *   can tell a clean pass from an unenforced one. Note *encountered*: the
+ *   list is built while walking, so a keyword sitting in a subschema this
+ *   value never reached (a property it does not carry, a `$defs` entry no
+ *   `$ref` took) is not in it. Validate a value that exercises the branch to
+ *   see its keywords.
+ * - **Remote and non-pointer `$ref`** (`http://...`, `other.json#/x`, and
+ *   `$id`-relative resolution). A `$ref` this validator cannot resolve
+ *   locally is reported as an error rather than treated as `true`.
+ *
+ * ## Two deliberate deviations, both in the reporting
+ *
+ * - When `type` fails, the keywords specific to that type are not also run,
+ *   so a number arriving where an object belongs produces one error rather
+ *   than one per property. The verdict is identical; only the error list is
+ *   shorter. `allOf`/`anyOf`/`oneOf`/`not` still run, since those can fail
+ *   independently of the type.
+ * - Errors stop accumulating at `maxErrors`, and the result says `truncated`.
+ *
+ * ## A bounded amount of work, and "undetermined" when it runs out
+ *
+ * `anyOf`/`oneOf`/`allOf` over `$ref`s that share a target multiply: a
+ * 1.3 KB schema can ask for 2^30 subschema evaluations, and the walk is
+ * synchronous. Every subschema evaluation is counted against a budget. So
+ * is every check whose cost follows the value's size rather than the
+ * schema's — a string's length or pattern, uniqueItems, an object's keys,
+ * each enum candidate and each (key, patternProperties pattern) test, and
+ * each error message built — so a small schema cannot spend the value's
+ * size once per leaf. When the budget runs out the walk stops and the
+ * result is `undetermined`, with `valid: false` and the reason — never a
+ * verdict either way. A failing branch is summarised in a bounded message,
+ * and a message is built only when it will be kept.
+ *
+ * The default budget ({@link defaultWorkLimit}) follows what an honest walk
+ * can cost. A schema written out as a tree (no `$ref` reached twice at one
+ * place) evaluates each of its subschemas at most once per value node, so a
+ * value node is allowed as many units as the schema has subschemas (at
+ * least {@link WORK_PER_VALUE_NODE}, at most {@link MAX_SCHEMA_FANOUT}); a
+ * wide or nested union over thousands of valid rows is answered. Only
+ * repeating a `$ref` at one place goes past that, which is the shape that
+ * multiplies. The floor is {@link DEFAULT_MAX_WORK} and the ceiling
+ * {@link MAX_DEFAULT_WORK}, a few seconds of the worst schemas measured.
+ *
+ * ## Depth is the value's
+ *
+ * A recursive schema walks as deep as the value does, so nesting is counted
+ * where the value nests — into an item or a property — not per `$ref` or
+ * branch. A value deeper than {@link MAX_VALUE_DEPTH}, or a schema and value
+ * nesting past {@link MAX_NESTING} walk frames together, is `undetermined`:
+ * the part not walked may be valid or not. A `$ref` that reaches itself at
+ * one position with nothing consumed between is a cycle, and an error.
+ *
+ * `pattern` is an unanchored ECMA-262 match, per the spec — `"pattern": "a"`
+ * matches `"banana"`.
+ */
+import { type RegexAnswers } from "./regex-answers";
 /** A schema is an object of keywords, or a boolean that accepts/rejects all. */
 export type Schema = boolean | Record<string, unknown>;
 /** One failure, addressed by a JSON Pointer into the value. */
@@ -16,9 +104,81 @@ export type ValidateOptions = {
     assertFormat: boolean;
     /** Stop collecting after this many errors. */
     maxErrors: number;
+    /**
+     * Most subschema evaluations before the answer is `undetermined`. Default:
+     * the larger of DEFAULT_MAX_WORK and WORK_PER_VALUE_NODE per value node.
+     */
+    maxWork: number;
+    /**
+     * A budget shared with other calls (ValidateRecords draws every row from
+     * one). When given, `maxWork` is ignored.
+     */
+    budget: WorkBudget;
+    /**
+     * Answers for the schema's `pattern` and `patternProperties` regexes,
+     * resolved in the worker by the calling tool (see `withRegexAnswers`). A
+     * question not answered yet is recorded there and read as "no match" for
+     * this pass, which the caller discards and runs again. Without it, each
+     * pattern runs on this thread through the bounded fallback.
+     */
+    regex: RegexAnswers;
+};
+/** Subschema evaluations allowed and spent; shared by reference. */
+export type WorkBudget = {
+    used: number;
+    readonly limit: number;
 };
+/** The budget floor: about a third of a second of the worst schemas measured (Apple silicon). */
+export declare const DEFAULT_MAX_WORK = 500000;
+/**
+ * The least work allowed per unit of the value's weight, so a large document
+ * is not refused for its size. A schema with more subschemas than this is
+ * allowed its subschema count instead.
+ */
+export declare const WORK_PER_VALUE_NODE = 64;
+/** The most work per unit of weight a schema's size earns. */
+export declare const MAX_SCHEMA_FANOUT = 1024;
+/**
+ * The most work a default budget allows, however large the value: about
+ * seven seconds of the worst schemas measured (Apple silicon, 0.3-0.5 us a
+ * unit). The walk is synchronous, so this is how long one call can hold the
+ * harness's thread.
+ */
+export declare const MAX_DEFAULT_WORK = 20000000;
+/** Nodes in a JSON value (itself included), counted iteratively, stopping at `cap`. */
+export declare function countValueNodes(value: unknown, cap?: number): number;
+/**
+ * A value's weight: one per node, and one more per CHARS_PER_UNIT
+ * characters of each string and key — the size the size-bound checks are
+ * charged in, so the budget grows with the value in the same units.
+ */
+export declare function valueWeight(value: unknown): number;
+/**
+ * Subschemas in `schema` written out as a tree, `$ref`s not followed, up to
+ * `cap`: what one value node can honestly be checked against. Counted
+ * iteratively, since a schema may nest deeper than the stack.
+ */
+export declare function schemaFanout(schema: unknown, cap?: number): number;
+/**
+ * The default budget for validating `value` against `schema`: the value's
+ * weight times what the schema allows per unit of it, between
+ * DEFAULT_MAX_WORK and MAX_DEFAULT_WORK.
+ */
+export declare function defaultWorkLimit(value: unknown, schema?: unknown): number;
 export type ValidationResult = {
+    /** Never true when `undetermined` is set. */
     valid: boolean;
+    /**
+     * Why no verdict could be reached, or null when `valid` is the verdict.
+     * Set when the work budget ran out: the errors listed are the ones found
+     * before it did, and the value may be valid or invalid.
+     */
+    undetermined: string | null;
+    /**
+     * True when `undetermined` is the work budget running out: no pattern
+     * answer can change that, so a caller resolving patterns in rounds stops.
+     */
+    workExhausted: boolean;
     errors: ValidationError[];
     /** True when `maxErrors` cut the list short. */
     truncated: boolean;
@@ -29,6 +189,16 @@ export type ValidationResult = {
      */
     unsupportedKeywords: string[];
 };
+/** Deepest value the walk follows; past it the answer is undetermined. */
+export declare const MAX_VALUE_DEPTH = 512;
+/**
+ * Most walk frames (a subschema evaluation inside another) at once, value
+ * and schema nesting together; past it the answer is undetermined. It keeps
+ * a deeply nested schema from overflowing the stack.
+ */
+export declare const MAX_NESTING = 2048;
+/** Longest message one error carries; nested branch reasons are cut here. */
+export declare const MAX_MESSAGE_CHARS = 1000;
 /**
  * Validate `value` against `schema`, returning every failure with a JSON
  * Pointer path. See the module comment for the exact supported subset; the