ata-validator 1.41.0 → 1.43.0

package/index.js

@@ -35,6 +35,65 @@ class TextRejection {
   }
 }
 
+// Errors built enriched where they fail by the rich combined function (see
+// makeRich in lib/enrich-site.js), for a validator whose errors are being read
+// with richErrors on. Presenting them is the ordering and the `related` links
+// presentErrors applies after enriching. Where the rich function does not
+// reject (the data changed under the read), the plain fallback is presented
+// the usual way.
+const { needsOrdering: _needsOrdering, sortErrorsBySchemaOrder: _sortErrors, attachRelated: _attachRelated } = require('./lib/rejections');
+let _enrichFnIdx = null;
+function _enrichOne(e, data) {
+  if (_enrichFnIdx === null) _enrichFnIdx = require('./lib/enrich-error').enrich;
+  return _enrichFnIdx(e, data !== undefined ? { data } : null);
+}
+function richBuilder(combRich, root, presentFallback, fallback, plain, cleanPlain) {
+  if (plain) {
+    // The runtime-shape combined function writes each error fresh and in the
+    // plain shape: no shared literal, no ordinal, no code or docUrl, no
+    // collapsed branches (lib/js-compiler.js, compileToJSCombined with
+    // runtimeShape). So without enrichment the list is the caller's as it is,
+    // once in schema order. Checking each error for those fields instead cost
+    // a megamorphic load per field per error across many schemas.
+    // tests/test_error_read_paths.js holds every error handed out to being
+    // the caller's own.
+    return (data) => {
+      const r = combRich(data);
+      if (r.valid || !r.errors || !r.errors.length) return presentFallback(fallback, data);
+      if (cleanPlain) return _needsOrdering(r.errors) ? _sortErrors(root, r.errors) : r.errors;
+      return presentFallback(r.errors, data);
+    };
+  }
+  return (data) => {
+    const r = combRich(data);
+    if (r.valid || !r.errors || !r.errors.length) return presentFallback(fallback, data);
+    const out = _needsOrdering(r.errors) ? _sortErrors(root, r.errors) : r.errors;
+    // A collapsed oneOf or anyOf comes out plain (no docUrl) and is enriched
+    // here, its branch errors with it, as presentErrors would.
+    for (let i = 0; i < out.length; i++) {
+      if (out[i].docUrl === undefined) out[i] = _enrichOne(out[i], data);
+    }
+    if (out.length > 1) _attachRelated(out);
+    return out;
+  };
+}
+
+// The rejection validate() returns once it is the one-pass combined function
+// (resultShape in compileToJSCombined): the errors are already built, plain,
+// fresh and in schema order. Serialises as the lazy rejection does.
+class EagerRejection {
+  constructor(errors) {
+    this.valid = false;
+    this.errors = errors;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+  _ataRaw() {
+    return this.errors;
+  }
+}
+
 function installCodegenPaths (ctx) {
   const { ABORT_EARLY_RESULT, HYBRID_TIER_CALLS, SIMDJSON_THRESHOLD, VALID_RESULT, _bindVerdict, _jsonSyntaxRejection, _mustReject, _verboseWrap, getNative, isV1Dialect, resolveSchemaByPath } = core._internals;
   const { jsFn, _isCodegen, preprocess, fusedRemove, options, schemaObj, useSimdjsonForLarge, _buildCombined, _buildErr } = ctx;
@@ -131,6 +190,36 @@ function installCodegenPaths (ctx) {
     return _safeCombined;
   };
 
+  // The error function on its own, probed the way errOnly probes it, or null.
+  const errFnIfSafe = () => {
+    _buildErr();
+    const efn = ctx.err();
+    if (!efn) return null;
+    try { efn({}, true); } catch { return null; }
+    return (x) => efn(x, true);
+  };
+
+  // The rich combined function, built and probed the way the plain one is,
+  // and only where the plain one passed its probe.
+  let _richProbed = false;
+  let _safeRich = null;
+  const richIfSafe = () => {
+    if (_richProbed) return _safeRich;
+    _richProbed = true;
+    if (!combinedIfSafe() || !ctx.buildRich) return null;
+    const fn = ctx.buildRich();
+    if (fn) {
+      try {
+        const probe = {};
+        if (schemaObj && schemaObj.properties) for (const k of Object.keys(schemaObj.properties)) probe[k] = "";
+        if (schemaObj && schemaObj.if && schemaObj.if.properties) for (const k of Object.keys(schemaObj.if.properties)) probe[k] = "";
+        fn(probe); fn({}); fn(null); fn(0);
+        _safeRich = fn;
+      } catch {}
+    }
+    return _safeRich;
+  };
+
   // What the hybrid path hands to its error slot: the combined function
   // when it is usable, since it validates and collects in one pass, and
   // the error generator otherwise. Same order the eager code chose, just
@@ -227,6 +316,38 @@ function installCodegenPaths (ctx) {
     // and used to call validate() to get the errors, which ran the verdict a
     // second time and built a second rejection around it.
     if (!preprocess) ctx.rejectBase = onReject;
+    // The rich combined function, for a validator whose errors are being read
+    // with richErrors on. See _ensureCompiled.
+    if (!preprocess) {
+      ctx.richBuilder = richBuilder;
+      // The plain combined function stands in where no rich one is built
+      // (richErrors off, or a schema source to frame errors from): its errors
+      // are presented, and enriched when asked, the usual way, without the
+      // rejection layers between.
+      // Where the plain combined function declines (oneOf, anyOf, an
+      // additionalProperties schema), the error function stands in, called
+      // directly rather than through the rejection layers. Its errors can be
+      // collapsed branches that still need presenting; only the combined
+      // function's are already in their final plain shape (isCleanShape).
+      ctx.oneShotRich = ctx.buildRich ? richIfSafe : () => combinedIfSafe() || errFnIfSafe();
+      ctx.oneShotPlain = !ctx.buildRich;
+      ctx.isCleanShape = (fn) => fn !== null && fn === _safeCombined;
+      ctx.isCombined = (fn) => fn !== null && fn === _safeCombined;
+      // validate() as the combined function in its result shape: built and
+      // probed here, null when it declines or throws on the probe.
+      ctx.onePassOf = (empty, fallback) => {
+        // A collapsed branch error is built in its final plain shape here
+        // (no ordering key in the runtime shape); its branch errors are put
+        // in order with the rest.
+        const sort = (errs) => (_needsOrdering(errs) ? _sortErrors(schemaObj, errs) : errs);
+        try {
+          const fn = jsCompiler.compileToJSCombined(schemaObj, VALID_RESULT, this._schemaMap.size > 0 ? this._schemaMap : null, this._userFormats, { runtimeShape: true, resultShape: { Rejection: EagerRejection, empty, sort, fallback, verdict: jsFn } });
+          if (!fn) return null;
+          fn({}); fn(null); fn(0);
+          return fn;
+        } catch { return null; }
+      };
+    }
   } else {
     // No hybrid factory, so the assembly needs the function itself rather
     // than a reference it can call later: build it now.
@@ -256,6 +377,7 @@ function installCodegenPaths (ctx) {
     // The verbose fields are added here, so a path around this layer would
     // miss them.
     ctx.rejectBase = null;
+    ctx.oneShotRich = null;
     this.validate = _verboseWrap(this.validate, this._schemaObj);
   }
   // The verdict methods answer validate()'s question without building the
@@ -381,7 +503,7 @@ function installCodegenPaths (ctx) {
 // The verdict function alone, for isValidObject() before a full compile: the
 // error and combined generators are left for the first rejection.
 installCodegenPaths.compileVerdict = function compileVerdict () {
-  const { compileCacheKey, _compileCache, _bindVerdict, _rememberInstance } = core._internals;
+  const { compileCacheKey, _compileCache, _compileCacheSet, _bindVerdict, _rememberInstance } = core._internals;
   if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
   const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
   const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
@@ -410,7 +532,7 @@ installCodegenPaths.compileVerdict = function compileVerdict () {
     // validator that later reuses this entry reports the same engine it
     // would have compiled to.
     if (!uf && !this._keywords) {
-      if (!cached) _compileCache.set(mapKey, { jsFn, combined: undefined, errFn: undefined, isCodegen: !!_cg, full: false });
+      if (!cached) _compileCacheSet(mapKey, { jsFn, combined: undefined, errFn: undefined, isCodegen: !!_cg, full: false });
       else cached.jsFn = jsFn;
     }
   }

package/lib/branch-collapse.js

@@ -40,25 +40,35 @@ function __ataScore (errs) {
   return errs.length * 100 + s; // primary: count, secondary: severity
 }
 
-// `br` is one entry per branch in declaration order: {valid, errors, title}.
+// `br` is one entry per branch in declaration order: {valid, errors} and a
+// `title`, or the titles in `titles` when given (the generated code passes
+// each branch's result as it is rather than copying it to add one).
 // Returns the single error to report, or null when the keyword is satisfied.
-function __ataCollapse (kw, br, pp, sp, o) {
-  const pass = br.filter((b) => b.valid);
+// oneOf passed by more than one branch; generated code builds it from a count.
+function __ataMulti (passIdx, total, pp, sp, o) {
+  const multi = {
+    code: 'ATA4002',
+    keyword: 'oneOf',
+    instancePath: pp || '',
+    path: pp || '',
+    schemaPath: sp,
+    message: 'value matched ' + passIdx.length + ' of ' + total + ' oneOf variants, expected exactly one',
+    params: { passingSchemas: passIdx },
+  };
+  if (o !== null) Object.defineProperty(multi, '_o', { value: o });
+  return multi;
+}
+
+function __ataCollapse (kw, br, pp, sp, o, titles) {
+  let passN = 0;
+  for (let i = 0; i < br.length; i++) if (br[i].valid) passN++;
+  const pass = { length: passN };
   if (kw === 'oneOf') {
     if (pass.length === 1) return null;
     if (pass.length > 1) {
       const passIdx = [];
       for (let i = 0; i < br.length; i++) if (br[i].valid) passIdx.push(i);
-      return {
-        code: 'ATA4002',
-        keyword: 'oneOf',
-        instancePath: pp || '',
-        path: pp || '',
-        schemaPath: sp,
-        _o: o,
-        message: 'value matched ' + pass.length + ' of ' + br.length + ' oneOf variants, expected exactly one',
-        params: { passingSchemas: passIdx },
-      };
+      return __ataMulti(passIdx, br.length, pp, sp, o);
     }
   } else if (pass.length >= 1) {
     return null;
@@ -70,17 +80,21 @@ function __ataCollapse (kw, br, pp, sp, o) {
     if (s < bs) { bs = s; bi = i; }
   }
   const best = br[bi];
-  return {
+  // The ordering key, when there is one, is not enumerable: the error is
+  // otherwise in the shape it is handed out in, and a caller that reads it
+  // as it comes (the combined function's one-pass result) does not copy it.
+  const none = {
     code: kw === 'oneOf' ? 'ATA4001' : 'ATA4003',
     keyword: kw,
     instancePath: pp || '',
     path: pp || '',
     schemaPath: sp,
-    _o: o,
     message: 'value matched 0 of ' + br.length + ' ' + kw + ' variants',
-    params: { variants: br.length, closest: bi, closestName: best.title || ('variant ' + (bi + 1)) },
+    params: { variants: br.length, closest: bi, closestName: (titles !== undefined ? titles[bi] : best.title) || ('variant ' + (bi + 1)) },
     branchErrors: best.errors,
   };
+  if (o !== null) Object.defineProperty(none, '_o', { value: o });
+  return none;
 }
 
 // The named-argument form the interpreter and the tests call.
@@ -88,12 +102,13 @@ function collapseBranches ({ keyword, branchResults, parentPath, parentSchemaPat
   return __ataCollapse(keyword, branchResults, parentPath, parentSchemaPath, ordinal === undefined ? null : ordinal);
 }
 
-// The three declarations as source, for the generated code to carry. Derived
+// The four declarations as source, for the generated code to carry. Derived
 // from the functions above rather than written out again, so a fix to one
 // cannot miss the other. `tests/test_branch_collapse.js` runs both.
 function embedSource () {
   return 'const __ATA_SEVERITY=' + JSON.stringify(__ATA_SEVERITY) + ';' +
     'const __ataScore=' + __ataScore.toString() + ';' +
+    'const __ataMulti=' + __ataMulti.toString() + ';' +
     'const __ataCollapse=' + __ataCollapse.toString() + ';';
 }
 

package/lib/enrich-error.js

@@ -185,40 +185,56 @@ function rankFor (keyword) {
 function enrich (rawErr, opts) {
   const data = opts && opts.data;
   const positions = opts && opts.positions;
-  const format = rawErr.params && rawErr.params.format;
-  // The native engine reports its own enum as a number. Translate it to the
-  // keyword and public code the JavaScript engines use, so an error means the
-  // same thing whichever engine produced it.
-  const fromAddon = typeof rawErr.code === 'number' ? fromNative(rawErr.code, format) : null;
-  const keyword = rawErr.keyword || (fromAddon && fromAddon.keyword);
-  // Prefer a code the codegen already attached (e.g. branch-collapse emits
-  // ATA4001/4002/4003 distinguishing zero/multi/anyOf failure modes). The
-  // keyword-derived lookup only finds the first match for `keyword: 'oneOf'`.
-  // A property that dependentRequired asks for is reported with the keyword
-  // `required`, and its documented code is ATA7005, not required's ATA7001.
-  // The error generator stamped 7005 and the other engines left it to the
-  // keyword here, so the same failure carried either code depending on which
-  // generator answered.
-  const dependent = keyword === 'required' && typeof rawErr.schemaPath === 'string' && rawErr.schemaPath.endsWith('/dependentRequired');
-  const code = (fromAddon && fromAddon.code) ||
-    (typeof rawErr.code === 'string' && rawErr.code) ||
-    (dependent && 'ATA7005') ||
-    codeFor(keyword, format) ||
-    'ATA9001';
-  const meta = CODES[code];
-  const path = rawErr.instancePath != null ? rawErr.instancePath : (rawErr.path || '');
-
+  // A literal the generated code shares between calls carries a slot for the
+  // fields that depend on nothing but the literal: worked out on the first
+  // read, taken from the slot after that.
+  let st = rawErr._t;
+  if (st === undefined || st.code === undefined) {
+    const format = rawErr.params && rawErr.params.format;
+    // The native engine reports its own enum as a number. Translate it to the
+    // keyword and public code the JavaScript engines use, so an error means the
+    // same thing whichever engine produced it.
+    const fromAddon = typeof rawErr.code === 'number' ? fromNative(rawErr.code, format) : null;
+    const keyword = rawErr.keyword || (fromAddon && fromAddon.keyword);
+    // Prefer a code the codegen already attached (e.g. branch-collapse emits
+    // ATA4001/4002/4003 distinguishing zero/multi/anyOf failure modes). The
+    // keyword-derived lookup only finds the first match for `keyword: 'oneOf'`.
+    // A property that dependentRequired asks for is reported with the keyword
+    // `required`, and its documented code is ATA7005, not required's ATA7001.
+    // The error generator stamped 7005 and the other engines left it to the
+    // keyword here, so the same failure carried either code depending on which
+    // generator answered.
+    const dependent = keyword === 'required' && typeof rawErr.schemaPath === 'string' && rawErr.schemaPath.endsWith('/dependentRequired');
+    const code = (fromAddon && fromAddon.code) ||
+      (typeof rawErr.code === 'string' && rawErr.code) ||
+      (dependent && 'ATA7005') ||
+      codeFor(keyword, format) ||
+      'ATA9001';
+    const meta = CODES[code];
+    const fixed = {
+      code,
+      message: rawErr.message || (meta && meta.headline) || 'validation failed',
+      keyword,
+      path: rawErr.instancePath != null ? rawErr.instancePath : (rawErr.path || ''),
+      expected: expectedFor(rawErr),
+      docUrl: DOC_BASE + code,
+      rank: rankFor(keyword),
+    };
+    if (st !== undefined && !fromAddon) Object.assign(st, fixed);
+    st = fixed;
+  }
+  const path = st.path;
   const at = data !== undefined ? resolveAt(rawErr, data) : MISSING;
 
   const out = {
-    code,
-    message: rawErr.message || (meta && meta.headline) || 'validation failed',
-    keyword,
+    code: st.code,
+    message: st.message,
+    keyword: st.keyword,
     path,
-    expected: expectedFor(rawErr),
+    expected: st.expected,
     received: at === MISSING ? undefined : reprValue(at),
     schemaPath: rawErr.schemaPath,
-    docUrl: DOC_BASE + code,
+    docUrl: st.docUrl,
     // Back-compat aliases (additive, present in both rich and legacy paths)
     instancePath: path,
     dataPath: path,
@@ -264,7 +280,7 @@ function enrich (rawErr, opts) {
 
   const detail = detailFor(rawErr, out);
   if (detail !== undefined) out.detail = detail;
-  out.rank = rankFor(keyword);
+  out.rank = st.rank;
 
   // Token-level anchor. `dataFrame` already carries the value span; `anchor`
   // adds the key span so a caret can sit on the property that is wrong rather
@@ -287,4 +303,4 @@ function enrich (rawErr, opts) {
   return out;
 }
 
-module.exports = { enrich, reprValue, expectedFor };
+module.exports = { enrich, reprValue, expectedFor, detailFor, rankFor, MISSING, DOC_BASE };

package/lib/enrich-site.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { CODES, codeFor } = require('./error-codes');
+const { suggestFor } = require('./suggestions');
+const { reprValue, expectedFor, detailFor, rankFor, MISSING, DOC_BASE } = require('./enrich-error');
+
+// Enrichment done where the error happens. The combined generator, once a
+// validator's errors are being read, calls `makeRich` at each failure with a
+// site record built at compile time by `errorSite` and the value it was
+// checking, and gets the same object `enrich` would build from the raw error:
+// same keys, same order, same values. What depends only on the site (code,
+// docUrl, rank, and `expected` when the params are fixed) is worked out once,
+// and the value comes from the generated code instead of a pointer walk. It is
+// for validate(data) without positions or a schema source; those reads keep
+// `enrich`. tests/test_rich_errors_generated.js holds the two to the same
+// output. A module of its own because only the code generator reaches it, and
+// ata-validator/lite, which enriches through `enrich`, should not carry it.
+const NO_EXPECTED = {};
+function errorSite (keyword, schemaPath, params, format) {
+  const dependent = keyword === 'required' && typeof schemaPath === 'string' && schemaPath.endsWith('/dependentRequired');
+  const code = (dependent && 'ATA7005') || codeFor(keyword, format) || 'ATA9001';
+  return {
+    code,
+    keyword,
+    schemaPath,
+    docUrl: DOC_BASE + code,
+    rank: rankFor(keyword),
+    headline: (CODES[code] && CODES[code].headline) || 'validation failed',
+    expected: params === undefined ? NO_EXPECTED : expectedFor({ keyword, params }),
+  };
+}
+
+function makeRich (site, path, params, message, value, root, spPrefix) {
+  // As resolveAt: a root that is null, undefined, '' or NaN resolves nothing.
+  const at = (!root && root !== 0 && root !== false) ? MISSING : value;
+  const out = {
+    code: site.code,
+    message: message || site.headline,
+    keyword: site.keyword,
+    path,
+    expected: site.expected === NO_EXPECTED ? expectedFor({ keyword: site.keyword, params }) : site.expected,
+    received: at === MISSING ? undefined : reprValue(at),
+    schemaPath: spPrefix === undefined ? site.schemaPath : spPrefix + site.schemaPath,
+    docUrl: site.docUrl,
+    instancePath: path,
+    dataPath: path,
+    params,
+    parentSchema: undefined,
+  };
+  const sugg = suggestFor(out, root, at === MISSING ? undefined : at);
+  if (sugg) out.suggestion = sugg;
+  const detail = detailFor({ keyword: site.keyword, params }, out);
+  if (detail !== undefined) out.detail = detail;
+  out.rank = site.rank;
+  return out;
+}
+
+module.exports = { errorSite, makeRich };

package/lib/interpreter.js

@@ -1255,6 +1255,12 @@ function createInterpreter(schema, options) {
 }
 
 module.exports = { createInterpreter };
+// The resolver, for the code generator: it resolves references at compile
+// time the way this engine does at run time (normalizeRefs in js-compiler).
+Object.defineProperty(module.exports, '_refInternals', {
+  value: { indexSchemas, resolveRef, FALLBACK_BASE },
+  enumerable: false,
+});
 // For lib/plan-source.js, which emits source from the same plans and must call
 // the same helpers so the two cannot answer differently.
 Object.defineProperty(module.exports, '_planInternals', {