ata-validator 1.49.0 → 1.50.0

package/lib/error-code-of.js

@@ -0,0 +1,22 @@
+'use strict';
+
+// The code a module stamps on an error, from its keyword (and format): the
+// first code in sorted order that names the keyword, the same rule as codeFor
+// in lib/error-codes.js and the table a module carries (lib/aot-impl.js).
+const { CODES } = require('./error-codes');
+
+const byKw = {};
+const byFmt = {};
+for (const code of Object.keys(CODES).sort()) {
+  const c = CODES[code];
+  if (byKw[c.keyword] === undefined) byKw[c.keyword] = code;
+  if (c.keyword === 'format' && c.format && byFmt[c.format] === undefined) byFmt[c.format] = code;
+}
+
+function codeOf(keyword, format) {
+  if (keyword === 'format' && format) { const h = byFmt[format]; return h === undefined ? 'ATA3099' : h; }
+  const h = byKw[keyword];
+  return h === undefined ? null : h;
+}
+
+module.exports = { codeOf, byKw, byFmt };

package/lib/error-runtime-entry.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// The error runtime that compiled modules share. A module built in the
+// compact shape carries only its verdict function and its schema with the
+// annotations taken out; when a document fails, it hands the document to this
+// runtime, which walks the same schema with the interpreted engine and returns
+// the error list. One copy serves every module of a build, so the error detail
+// a module used to carry as generated code is paid for once.
+//
+// What comes back is what `validate()` returns on the runtime Validator with
+// `richErrors: false`, plus the `code` and `docUrl` a module stamps: the same
+// errors, in schema declaration order.
+//
+// It loads the interpreter without its plan compiler, which adds speed and
+// no answers: lib/error-runtime.js packs this file and what it requires into
+// the runtime a build writes, and `ata-validator/error-runtime` exports it
+// for bundler plugins.
+
+const { createInterpreter } = require('./interpreter-core');
+const { sortErrorsByRank } = require('./error-sort-rank');
+
+const DOC = 'https://ata-validator.com/e/';
+
+function stamp(errors, codeOf) {
+  const out = new Array(errors.length);
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    // A collapsed oneOf/anyOf error comes with its code and no docUrl, as
+    // the module's own collector leaves it; only its branches are stamped.
+    if (e.code !== undefined) {
+      const x = {};
+      for (const k in e) if (k !== '_o' && k !== 'branchErrors') x[k] = e[k];
+      if (Array.isArray(e.branchErrors)) x.branchErrors = stamp(e.branchErrors, codeOf);
+      out[i] = x;
+      continue;
+    }
+    let code;
+    {
+      code = e.keyword === 'required' && typeof e.schemaPath === 'string' && e.schemaPath.endsWith('/dependentRequired')
+        ? 'ATA7005'
+        : codeOf(e.keyword, e.params && e.params.format);
+    }
+    const x = code === null || code === undefined ? {} : { code };
+    for (const k in e) if (k !== 'code' && k !== '_o' && k !== 'docUrl' && k !== 'branchErrors') x[k] = e[k];
+    if (code !== null && code !== undefined) x.docUrl = DOC + code;
+    if (Array.isArray(e.branchErrors)) x.branchErrors = stamp(e.branchErrors, codeOf);
+    out[i] = x;
+  }
+  return out;
+}
+
+// The error list for a document `interp` rejects, as a module reports it, or
+// null when there is no detail to give.
+function errorsOf(interp, schema, codeOf, data) {
+  let raw;
+  try {
+    raw = interp.validate(data).errors;
+  } catch (e) {
+    // Data nested deeper than the walk's stack allows: no detail, which the
+    // module reports as its ATA9000 stub. The verdict came from the module.
+    if (e instanceof RangeError) return null;
+    throw e;
+  }
+  if (!raw || raw.length === 0) return null;
+  const ordered = raw.length > 1 || (raw[0] && Array.isArray(raw[0].branchErrors))
+    ? sortErrorsByRank(schema, raw)
+    : raw;
+  return stamp(ordered, codeOf);
+}
+
+function interpreterOptions(options) {
+  return { v1: !!(options && options.v1), flat: !!(options && options.flat) };
+}
+
+// schema: the schema the module's verdict was compiled from, after dialect
+// normalization. codeOf(keyword, format): the module's own code table.
+function createErrors(schema, codeOf, options) {
+  let interp = null;
+  return function errorsFor(data) {
+    if (interp === null) interp = createInterpreter(schema, interpreterOptions(options));
+    return errorsOf(interp, schema, codeOf, data);
+  };
+}
+
+module.exports = { createErrors, errorsOf, interpreterOptions };

package/lib/error-runtime.js

@@ -0,0 +1,152 @@
+'use strict';
+
+// Source of the error runtime that compact modules import (see
+// lib/error-runtime-entry.js for what it does). It is put together from the
+// library's own files when a build asks for it, so there is no second copy of
+// the interpreter to keep in step: each file becomes a function in a small
+// module table, and require() inside them resolves against that table. The
+// interpreter comes without its plan compiler (lib/interpreter-core.js), which
+// produces the same errors.
+//
+// The output is not minified. It goes through the application's bundler like
+// the modules that import it.
+
+const fs = require('fs');
+const path = require('path');
+
+const FILES = [
+  'error-runtime-entry',
+  'interpreter-core',
+  'error-sort-rank',
+  'schema-order',
+  'branch-collapse',
+  'safe-regex',
+  'unique-items',
+  'formats',
+];
+// The parts a build can leave out when none of its schemas needs them. The
+// decision is made on the schemas the runtime walks (as embedded, see
+// runtimeFeatures) and errs toward keeping a part: a key with that name
+// anywhere, even inside an enum value, keeps it. A part left out is replaced
+// by a stub that throws, which a schema without that keyword cannot reach.
+const OPTIONAL = {
+  formats: { keys: ['format'], stub: 'module.exports = {};' },
+  'safe-regex': { keys: ['pattern', 'patternProperties'], stub: "module.exports = { compileSafe() { throw new Error('ata error runtime: built without the pattern engine'); } };" },
+  'unique-items': { keys: ['uniqueItems', 'enum', 'const'], stub: "function no() { throw new Error('ata error runtime: built without deep equality'); }\nmodule.exports = { allDistinct: no, duplicatePair: no, _deq: no };" },
+};
+
+// Which optional parts these schemas need: { formats, 'safe-regex',
+// 'unique-items' } as booleans.
+function runtimeFeatures(schemas) {
+  const keys = new Set();
+  const seen = new Set();
+  const walk = (n) => {
+    if (n === null || typeof n !== 'object' || seen.has(n)) return;
+    seen.add(n);
+    if (Array.isArray(n)) { for (const x of n) walk(x); return; }
+    for (const k of Object.keys(n)) { keys.add(k); walk(n[k]); }
+  };
+  for (const s of schemas) walk(s);
+  const out = {};
+  for (const [part, { keys: ks }] of Object.entries(OPTIONAL)) out[part] = ks.some((k) => keys.has(k));
+  return out;
+}
+
+function codeTable() {
+  const { byKw, byFmt } = require('./error-code-of');
+  return { byKw, byFmt };
+}
+
+// Lines that hold nothing but a // comment are about half of these files.
+// They go, unless the line sits inside a template literal (tracked by
+// counting backticks on the lines before it) or the file is one whose
+// templates carry such lines on purpose (formats.js builds code from them).
+const KEEP_COMMENTS = new Set(['formats']);
+function dropCommentLines(src, name) {
+  if (KEEP_COMMENTS.has(name)) return src;
+  const out = [];
+  let inTemplate = false;
+  for (const line of src.split('\n')) {
+    if (!inTemplate && /^\s*\/\//.test(line)) continue;
+    if (!inTemplate && line.trim() === '') continue;
+    out.push(line);
+    const ticks = (line.match(/`/g) || []).length;
+    if (ticks % 2 === 1) inTemplate = !inTemplate;
+  }
+  return out.join('\n');
+}
+
+const _cache = new Map();
+
+// The files a schema-mode runtime adds: the verdict comes from the
+// interpreter too, with its plan compiler for schemas used often.
+const SCHEMA_FILES = ['schema-runtime-entry', 'interpreter', 'plan-compiler'];
+
+// features: from runtimeFeatures, or omitted for a runtime with every part.
+// schemaMode: also carry the verdict (createValidator), for schema modules.
+function errorRuntimeSource(format, version, features, schemaMode) {
+  const want = (part) => !features || features[part] !== false;
+  const key = (format === 'cjs' ? 'cjs' : 'esm') + ':' + Object.keys(OPTIONAL).map((p) => (want(p) ? '1' : '0')).join('') + (schemaMode ? ':schema' : '');
+  const hit = _cache.get(key);
+  if (hit !== undefined) return hit;
+  const defs = [];
+  for (const name of schemaMode ? FILES.concat(SCHEMA_FILES) : FILES) {
+    const src = OPTIONAL[name] !== undefined && !want(name)
+      ? OPTIONAL[name].stub
+      : dropCommentLines(fs.readFileSync(path.join(__dirname, name + '.js'), 'utf8'), name);
+    defs.push(`${JSON.stringify(name)}: function (module, exports, require) {\n${src}\n}`);
+  }
+  const { byKw, byFmt } = codeTable();
+  const body = `// Auto-generated by ata-validator ${version}, do not edit.
+// The error runtime shared by the compact modules of one build. It imports
+// nothing. Re-run the build after upgrading ata.
+'use strict';
+const _ataDefs = {
+${defs.join(',\n')}
+};
+const _ataCache = {};
+function _ataRequire(spec) {
+  const name = spec.replace(/^\\.\\//, '').replace(/\\.js$/, '');
+  const hit = _ataCache[name];
+  if (hit !== undefined) return hit.exports;
+  const def = _ataDefs[name];
+  if (def === undefined) throw new Error('ata error runtime: missing module ' + spec);
+  const module = { exports: {} };
+  _ataCache[name] = module;
+  def(module, module.exports, _ataRequire);
+  return module.exports;
+}
+const _ataKw = ${JSON.stringify(byKw)};
+const _ataFmt = ${JSON.stringify(byFmt)};
+function _ataCode(k, f) {
+  if (k === 'format' && f) { const h = _ataFmt[f]; return h === undefined ? 'ATA3099' : h; }
+  const h = _ataKw[k];
+  return h === undefined ? null : h;
+}
+// The modules are evaluated on the first call, not when this file loads.
+function createErrors(schema, options) { return _ataRequire('error-runtime-entry').createErrors(schema, _ataCode, options); }
+function compileSafe(src) { return _ataRequire('safe-regex').compileSafe(src); }
+${schemaMode ? "function createValidator(schema, options) { return _ataRequire('schema-runtime-entry').createValidator(schema, _ataCode, options); }\n" : ''}
+const ataVersion = ${JSON.stringify(version)};
+
+// Warm-up, in a browser only: the runtime's code compiles on its first use,
+// which a page would otherwise pay for on its first rejected document, about
+// a millisecond. When the browser is idle, one small error list is built here
+// instead, once, so the first real one finds the code compiled. Nothing it
+// does reaches a caller.
+const WARM_SCHEMA = { type: 'object', properties: { a: { type: 'string' }, b: { type: 'integer', minimum: 0 }, c: { anyOf: [{ type: 'string' }, { type: 'null' }] }, f: { type: 'string', format: 'email' } }, required: ['d'], additionalProperties: false };
+function warm() { try { createErrors(WARM_SCHEMA, { flat: true })({ a: 1, b: -1, c: 2, f: 'x', e: 0 }); } catch (_) {} }
+if (typeof requestIdleCallback === 'function') { try { requestIdleCallback(warm); } catch (_) {} }
+// In Node the same happens once the event loop is first free after start-up,
+// on a timer that does not keep the process alive: a script that exits at
+// once never runs it, and a server has it done before its first request.
+else if (typeof process === 'object' && process !== null && process.versions && process.versions.node && typeof setTimeout === 'function') { try { const t = setTimeout(warm, 0); if (t && typeof t.unref === 'function') t.unref(); } catch (_) {} }
+`;
+  const out = format === 'cjs'
+    ? body + `module.exports = { createErrors, compileSafe, ${schemaMode ? 'createValidator, ' : ''}ataVersion };\n`
+    : body + `export { createErrors, compileSafe, ${schemaMode ? 'createValidator, ' : ''}ataVersion };\n`;
+  _cache.set(key, out);
+  return out;
+}
+
+module.exports = { errorRuntimeSource, runtimeFeatures, codeTable };

package/lib/error-sort-rank.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// Declaration-order sorting for the shared error runtime
+// (lib/error-runtime-entry.js), in its own file so the runtime Validator and
+// ata-validator/lite, which sort by ordinals (lib/error-sort.js), do not carry
+// it.
+const { rankFor: schemaRank } = require('./schema-order');
+
+// The same order from ranks alone: a rank is the path of child indexes from
+// the root to the node an error names, built by walking that one path, while
+// the ordinals above number every node of the schema on the first sort. The
+// shared error runtime sorts this way, so a rejection costs a walk of the
+// paths it reports, not of the schema. Comparing ranks segment by segment is
+// the pre-order relation the ordinals encode (see lib/schema-order.js), and a
+// path behind a local `$ref` ranks inside its target as the ordinal's tie
+// does; the runtime only takes schemas whose references stay inside them. An
+// error with no place in the document keeps the place of the one before it.
+function compareRanks(a, b) {
+  const m = Math.min(a.length, b.length);
+  for (let k = 0; k < m; k++) if (a[k] !== b[k]) return a[k] - b[k];
+  return a.length - b.length;
+}
+
+function sortErrorsByRank(rootSchema, errors) {
+  let out = null;
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    const b = e !== null && typeof e === 'object' ? e.branchErrors : undefined;
+    if (!Array.isArray(b) || b.length === 0) continue;
+    const sb = sortErrorsByRank(rootSchema, b);
+    if (sb === b) continue;
+    if (out === null) out = errors.slice();
+    out[i] = Object.assign({}, e, { branchErrors: sb });
+  }
+  if (out !== null) errors = out;
+  const n = errors.length;
+  if (n < 2) return errors;
+  const keys = new Array(n);
+  let prev = [];
+  let sorted = true;
+  for (let i = 0; i < n; i++) {
+    let r = schemaRank(rootSchema, errors[i].schemaPath);
+    if (r === null) r = prev;
+    keys[i] = r;
+    if (i > 0 && compareRanks(prev, r) > 0) sorted = false;
+    prev = r;
+  }
+  if (sorted) return errors;
+  const res = errors.slice();
+  for (let i = 1; i < n; i++) {
+    const k = keys[i];
+    const e = res[i];
+    let j = i - 1;
+    while (j >= 0 && compareRanks(keys[j], k) > 0) { keys[j + 1] = keys[j]; res[j + 1] = res[j]; j--; }
+    keys[j + 1] = k;
+    res[j + 1] = e;
+  }
+  return res;
+}
+
+module.exports = { sortErrorsByRank };