ata-validator 1.34.0 → 1.36.0

package/lib/rejections.js

@@ -0,0 +1,329 @@
+'use strict';
+
+// The rejection objects validate() and validateJSON() return, and the helpers
+// that build their errors on first read: declaration-order sorting,
+// enrichment, typo correlation and source frames. Shared by the validator core
+// and by the wrapper around a compiled module, so both report errors through
+// the same code.
+
+const { ordinalFor: schemaOrdinal, rankFor: schemaRank } = require('./schema-order');
+const { setDiagnosticSource: attachDiagnosticSource } = require('./diagnostic-source');
+
+// Rejection result with errors materialized on first read. The accessor
+// lives on the prototype so constructing one is a plain allocation; an
+// object-literal getter would create a closure and define an accessor
+// property on every rejection, which showed up as the single largest cost
+// on the rejection path. `toJSON` keeps JSON.stringify output identical to
+// the eager shape. Note for tests: deepStrictEqual against a plain object
+// compares prototypes; read `.errors` and compare that.
+class LazyRejection {
+  constructor(build, data, buildRaw) {
+    this.valid = false;
+    this._build = build;
+    this._data = data;
+    this._errors = null;
+    this._buildRaw = buildRaw;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+  // Raw shape for consumers that carry only message and path, such as the
+  // Standard Schema bridge: schema order, no enrichment. Reading `errors`
+  // afterwards still enriches through its own build.
+  _ataRaw() {
+    return this._buildRaw ? this._buildRaw(this._data) : this.errors;
+  }
+}
+Object.defineProperty(LazyRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._errors === null) this._errors = this._build(this._data);
+    return this._errors;
+  },
+});
+
+let _enrichFn = null;
+function _enrichLazy(e, opts) {
+  if (_enrichFn === null) _enrichFn = require('./enrich-error').enrich;
+  return _enrichFn(e, opts);
+}
+
+// The rejection the rich-errors wrapper returns. `errors` is built on first
+// read and cached; `_ataRaw()` is the raw, schema-ordered list for consumers
+// that carry only message and path, such as the Standard Schema bridge.
+// Prototype accessors, not per-instance ones: see LazyRejection.
+class RichRejection {
+  // `rawInput` is the JSON text validateJSON was given, or null for validate(data).
+  // The position map it implies is built in the `errors` getter, not here: it is
+  // a full walk of the document, it is only ever read through an error's
+  // dataFrame, and building it on every rejection cost a caller that reads
+  // `.valid` about 460 microseconds on a 50 KB document. Holding the text rather
+  // than reading `self._lastRawInput` later also keeps the result independent of
+  // what the instance does after this call returns.
+  constructor(result, data, rawInput, self, root, enrich) {
+    this.valid = false;
+    this._result = result;
+    this._data = data;
+    this._rawInput = rawInput;
+    this._self = self;
+    this._root = root;
+    this._enrich = enrich;
+    this._cached = null;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+  _ataRaw() {
+    let raw = this._result.errors || [];
+    if (raw.length > 1) raw = sortErrorsBySchemaOrder(this._root, raw);
+    return raw;
+  }
+}
+Object.defineProperty(RichRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._cached === null) {
+      const self = this._self;
+      const enrich = this._enrich;
+      let raw = this._result.errors || [];
+      if (raw.length > 1) raw = sortErrorsBySchemaOrder(this._root, raw);
+      // The position map, resolved now that an error is actually being read.
+      let positions = null;
+      if (enrich && raw.length && this._rawInput != null) {
+        positions = self._pos().targeted(this._rawInput, wantedPointersFor(raw));
+        if (positions) self._posCache.reset();
+      }
+      // One options object for the whole list, not one per error.
+      const opts = enrich && raw.length
+        ? {
+            data: this._data,
+            positions,
+            schemaPositions: self._schemaPositions,
+            schemaFile: self._source ? self._source.path : undefined,
+          }
+        : null;
+      const cached = opts
+        ? raw.map((e) => enrich(e, opts))
+        // The v0.14 shape is a fixed key set; the ordering key the
+        // generated code carries is dropped from it here.
+        : raw.map(stripOrdinal);
+      // Correlation is published, never applied. Both halves of a typo pair
+      // stay in the array; `related` only says they are one mistake, so a
+      // wrong pairing costs a sentence rather than a hidden violation.
+      if (enrich && cached.length > 1) attachRelated(cached);
+      // No diagnostic payload here. validate(data) is the library hot path,
+      // and attaching one cost about 100 ns per rejection for a consumer
+      // that never renders. The text path attaches it, and a renderer given
+      // `{ data }` builds frames for object input on request.
+      this._cached = cached;
+    }
+    return this._cached;
+  },
+});
+
+// The rejection validateJSON returns. Everything the text path adds over
+// validate(data), the value tree enrichment needs, the position map, the
+// diagnostic payload, happens on first access to `.errors`. Reading `.valid`
+// touches none of it. The JSON text is held here rather than read back off the
+// validator, so the result does not depend on what the instance does next.
+class LazyJsonRejection {
+  constructor(result, jsonStr, self, enrich) {
+    this.valid = false;
+    this._result = result;
+    this._jsonStr = jsonStr;
+    this._self = self;
+    this._enrich = enrich;
+    this._cached = null;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+}
+Object.defineProperty(LazyJsonRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._cached !== null) return this._cached;
+    const self = this._self;
+    const enrich = this._enrich;
+    const jsonStr = this._jsonStr;
+    // Reading the inner errors realizes the inner lazy layer, if there was one.
+    const raw = this._result.errors || [];
+    if (!raw.length) { this._cached = raw; return raw; }
+
+    // The enrich pass plucks `received` from the value tree and the suggestion
+    // engine (required-typo, format hints, coercion nudges) walks it too.
+    let parsedData;
+    try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
+    // What was checked is the document after defaults, coercion and removal,
+    // so `received` has to come from that, as it does for validate(). A
+    // default that failed its own schema has no value in the text at all.
+    if (parsedData !== undefined && self._preprocess) self._preprocess(parsedData);
+
+    // Errors the inner path already enriched carry a `received` key: enrich()
+    // always sets one, even when there is no value to show. `code` is not a
+    // safe signal, because branch-collapse attaches codes to raw errors, and
+    // `docUrl` is not either, because the generated error functions stamp it
+    // on raw errors; taking it as the signal left those errors without
+    // `received` or a suggestion on the text path while validate() had both.
+    if (!raw[0] || !('received' in raw[0])) {
+      const positions = self._pos().targeted(jsonStr, wantedPointersFor(raw));
+      // Declaration order, as validate() applies it; the text path used to
+      // enrich in emission order.
+      const ordered = raw.length > 1 ? sortErrorsBySchemaOrder(self._schemaObj, raw) : raw;
+      const enrichOpts = {
+        data: parsedData,
+        positions,
+        schemaPositions: self._schemaPositions,
+        schemaFile: self._source ? self._source.path : undefined,
+      };
+      const enriched = ordered.map((e) => enrich(e, enrichOpts));
+      if (enriched.length > 1) attachRelated(enriched);
+      attachDiagnosticSource(enriched, {
+        data: parsedData,
+        text: jsonStr,
+        positions,
+        schema: self._schemaObj,
+        mutatesInput: self._mutatesInput === true,
+      });
+      if (positions) self._posCache.reset();
+      this._cached = enriched;
+      return enriched;
+    }
+
+    // Already enriched, so the frames are usually attached too. Only a gap in
+    // them is worth another walk of the document: resolving the map to discover
+    // there was nothing to fill cost a second full walk on every rejection.
+    if (raw.some((e) => e && !e.dataFrame)) {
+      const positions = self._pos().targeted(jsonStr, wantedPointersFor(raw.filter((e) => e && !e.dataFrame)));
+      if (positions) {
+        for (const e of raw) {
+          if (e && !e.dataFrame) {
+            const path = e.path != null ? e.path : (e.instancePath || '');
+            const p = positions[path];
+            if (p) e.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
+          }
+        }
+        self._posCache.reset();
+      }
+    }
+    if (raw.length > 1) attachRelated(raw);
+    attachDiagnosticSource(raw, {
+      data: parsedData,
+      text: jsonStr,
+      schema: self._schemaObj,
+      mutatesInput: self._mutatesInput === true,
+    });
+    this._cached = raw;
+    return raw;
+  },
+});
+
+// The pointers a set of errors will ask the position map about. lib/enrich-error
+// looks up the error's own path, and for an additional or unevaluated property
+// the child pointer named in `params`, unescaped, which is the form it asks for.
+// The escaped form goes in too: including a pointer that is never read costs
+// nothing, and the cache answers anything outside this set from the full map
+// rather than reporting no position.
+function wantedPointersFor (errors) {
+  const wanted = new Set();
+  for (const e of errors) {
+    if (!e) continue;
+    const path = e.path != null ? e.path : (e.instancePath || '');
+    wanted.add(path);
+    if (e.instancePath != null && e.instancePath !== path) wanted.add(e.instancePath);
+    const params = e.params;
+    const named = params && (params.additionalProperty || params.unevaluatedProperty);
+    if (typeof named === 'string') {
+      wanted.add(path + '/' + named);
+      if (named.indexOf('~') !== -1 || named.indexOf('/') !== -1) {
+        wanted.add(path + '/' + named.replace(/~/g, '~0').replace(/\//g, '~1'));
+      }
+    }
+  }
+  return wanted;
+}
+
+// A raw error without the `_o` ordering key, for the legacy error shape.
+function stripOrdinal(e) {
+  if (e === null || typeof e !== 'object' || e._o === undefined) return e;
+  const out = {};
+  for (const k in e) if (k !== '_o') out[k] = e[k];
+  return out;
+}
+
+// Errors in schema declaration order. Each error's key is its schemaPath's
+// pre-order ordinal in the root schema: written into the literal by the code
+// generator (`_o`), looked up once per path otherwise. Errors behind the same
+// `$ref` share the ordinal of that `$ref`, and among themselves go by their
+// place in the target (rankFor), so they come out in the order they would
+// inline, whichever engine produced them. Most rejections come out already
+// ordered, and those return without sorting or allocating.
+function sortErrorsBySchemaOrder(rootSchema, errors) {
+  const n = errors.length;
+  const keys = new Array(n);
+  let sorted = true;
+  let prev = -1;
+  let prevPath = null;
+  for (let i = 0; i < n; i++) {
+    const e = errors[i];
+    let o = typeof e._o === 'number' ? e._o : schemaOrdinal(rootSchema, e.schemaPath);
+    // An error with no place in this document (an appended custom-keyword
+    // error, a path into another schema) stays next to the error before it,
+    // which is where the rank comparison left it too.
+    if (o === null) o = prev < 0 ? 0 : prev;
+    keys[i] = o;
+    if (o < prev || (o === prev && sorted && e.schemaPath !== prevPath && tieOrder(rootSchema, prevPath, e.schemaPath) > 0)) sorted = false;
+    prev = o;
+    prevPath = e.schemaPath;
+  }
+  if (sorted) return errors;
+  // Error lists are short. A stable insertion sort over the integer keys
+  // moves the errors in tandem with no index array; equal keys fall back to
+  // the rank only when the paths differ.
+  const out = errors.slice();
+  for (let i = 1; i < n; i++) {
+    const k = keys[i];
+    const e = out[i];
+    let j = i - 1;
+    while (j >= 0 && (keys[j] > k || (keys[j] === k && tieOrder(rootSchema, out[j].schemaPath, e.schemaPath) > 0))) {
+      keys[j + 1] = keys[j]; out[j + 1] = out[j]; j--;
+    }
+    keys[j + 1] = k;
+    out[j + 1] = e;
+  }
+  return out;
+}
+
+// Order of two paths with the same ordinal: positive when `a` belongs after
+// `b`. Zero keeps them as they are, for identical paths and for paths
+// outside this document.
+function tieOrder(rootSchema, a, b) {
+  if (a === b) return 0;
+  const ra = schemaRank(rootSchema, a), rb = schemaRank(rootSchema, b);
+  if (ra === null || rb === null) return 0;
+  const m = Math.min(ra.length, rb.length);
+  for (let k = 0; k < m; k++) if (ra[k] !== rb[k]) return ra[k] - rb[k];
+  return ra.length - rb.length;
+}
+
+// Resolved once. A require() inside the function was re-resolving the path
+// on every rejection, which the profile showed as internalModuleStat at the
+// top of the reject path, above the correlation it was loading.
+let _correlateTypos = null;
+function attachRelated (errors) {
+  if (_correlateTypos === null) _correlateTypos = require('./correlate').correlateTypos;
+  const pairs = _correlateTypos(errors);
+  if (pairs === null) return errors;
+  for (const [from, to] of pairs) {
+    const e = errors[from];
+    if (!e) continue;
+    if (e.related) { if (!e.related.includes(to)) e.related.push(to); }
+    else e.related = [to];
+  }
+  return errors;
+}
+
+module.exports = { LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, attachRelated, sortErrorsBySchemaOrder, stripOrdinal, wantedPointersFor };

package/lib/schema-order.js

@@ -11,6 +11,11 @@
 // generator can compute it once per error site instead of the reader
 // deriving it from the path string on every rejection.
 //
+// A path that runs on through a `$ref` names keys the referencing node does
+// not have. Its ordinal is that of the `$ref` key, which several paths then
+// share; its rank carries on inside the target, and the reader uses the rank
+// to order the paths that share an ordinal.
+//
 // Both are memoized per root schema; a validator's root never changes.
 
 const _keyIndexCache = new WeakMap();
@@ -56,12 +61,12 @@ function computeRank(rootSchema, schemaPath) {
   const rank = [];
   let node = rootSchema;
   let start = 1;
+  let hops = 0;
   while (start <= schemaPath.length) {
     let end = schemaPath.indexOf('/', start);
     if (end < 0) end = schemaPath.length;
     if (end === start) { start = end + 1; continue; }
     const seg = unescapePointerSegment(schemaPath.slice(start, end));
-    start = end + 1;
     if (node == null || typeof node !== 'object') break;
     if (Array.isArray(node)) {
       const idx = Number(seg);
@@ -70,14 +75,53 @@ function computeRank(rootSchema, schemaPath) {
       node = node[idx];
     } else {
       const idx = keyIndex(node, seg);
-      if (idx < 0) break;
+      if (idx < 0) {
+        // An evaluation path runs on through a `$ref` into its target without
+        // naming it. Ranking the rest inside the target, as if the target sat
+        // under the `$ref` key, orders errors behind a reference by the
+        // target's declaration order, as they are ordered inline.
+        const target = hops < 64 ? localTarget(rootSchema, node) : null;
+        if (target === null) break;
+        hops++;
+        rank.push(keyIndex(node, '$ref'));
+        node = target;
+        continue;
+      }
       rank.push(idx);
       node = node[seg];
     }
+    start = end + 1;
   }
   return rank;
 }
 
+// The schema a node's `$ref` names, when it is a pointer into this document.
+function localTarget(rootSchema, node) {
+  const ref = node.$ref;
+  if (typeof ref !== 'string' || ref.charCodeAt(0) !== 35) return null;
+  if (ref.length > 1 && ref.charCodeAt(1) !== 47) return null;
+  let t = rootSchema;
+  let start = 2;
+  while (start <= ref.length && ref.length > 1) {
+    let end = ref.indexOf('/', start);
+    if (end < 0) end = ref.length;
+    let seg = ref.slice(start, end);
+    if (seg.indexOf('%') >= 0) { try { seg = decodeURIComponent(seg); } catch { return null; } }
+    seg = unescapePointerSegment(seg);
+    if (t === null || typeof t !== 'object') return null;
+    // Normalization renames draft-07 `definitions` to `$defs` and leaves the
+    // pointers as written; the resolvers read either name as the other.
+    if (!Object.prototype.hasOwnProperty.call(t, seg)) {
+      const alias = seg === 'definitions' ? '$defs' : seg === '$defs' ? 'definitions' : null;
+      if (alias === null || !Object.prototype.hasOwnProperty.call(t, alias)) return null;
+      seg = alias;
+    }
+    t = t[seg];
+    start = end + 1;
+  }
+  return t !== null && typeof t === 'object' && t !== node ? t : null;
+}
+
 // Pre-order numbering of every node in the schema, keyed by its pointer as
 // it appears in a schemaPath (segments escaped). Built once per root, on the
 // first ask. Cyclic structures are guarded; a schema object can contain
@@ -115,13 +159,19 @@ function ordinalFor(rootSchema, schemaPath) {
   // Walk back to the longest prefix that exists. Paths through a keyword's
   // value that is a primitive, or through a key the schema does not have,
   // land on the nearest enclosing node.
+  // A path that runs on through a `$ref` lands on its `$ref` key, so errors
+  // behind a reference sort where the `$ref` is declared among its siblings;
+  // rankFor orders them among themselves.
   let p = schemaPath;
   while (true) {
     const cut = p.lastIndexOf('/');
     if (cut < 0) return 0;
     p = p.slice(0, cut);
     const o = map.get(p);
-    if (o !== undefined) return o;
+    if (o !== undefined) {
+      const r = map.get(p + '/$ref');
+      return r !== undefined ? r : o;
+    }
   }
 }