ata-validator 1.38.0 → 1.39.2

package/README.md

@@ -4,6 +4,7 @@ JSON Schema validation that compiles for speed and still runs where code generat
 
 [![npm](https://img.shields.io/npm/v/ata-validator)](https://www.npmjs.com/package/ata-validator)
 [![License](https://img.shields.io/npm/l/ata-validator)](LICENSE)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ata-core/ata-validator/badge)](https://scorecard.dev/viewer/?uri=github.com/ata-core/ata-validator)
 
 1.0 is a stability commitment: see [docs/STABILITY.md](docs/STABILITY.md) for the semver, deprecation, and error-code guarantees.
 
@@ -32,13 +33,13 @@ npm install --save-dev ata-validator
 npx ata build 'schemas/*.json' --out-dir src/generated
 ```
 
-The `ata-validator` package itself is pure JavaScript. The native accelerator (simdjson parsing, parallel NDJSON, buffer APIs) ships as per-platform optional packages that npm installs automatically where they fit, the same pattern Vite uses for esbuild. Seven targets are built: macOS on arm64 and x64, Linux on x64 and arm64 against both glibc and musl, and Windows on x64. A platform without a prebuild still installs and validates, on the pure-JS engine. For a guaranteed zero-binary install:
+The `ata-validator` package itself is pure JavaScript. The native accelerator (simdjson parsing, parallel NDJSON, buffer APIs) ships as per-platform optional packages that npm installs automatically where they fit, the same pattern Vite uses for esbuild. Seven targets are built: macOS on arm64 and x64, Linux on x64 and arm64 against both glibc (2.17 or later, below the 2.28 Node itself needs) and musl, and Windows on x64. A platform without a prebuild still installs and validates, on the pure-JS engine. For a guaranteed zero-binary install:
 
 ```bash
 npm install ata-validator --omit=optional
 ```
 
-or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1301 of 1301 Draft 2020-12 cases. Only the buffer and parallel APIs (`isValid` on raw buffers, `countValid`, `batchIsValid`, `validateAndParse`) need the native engine and say so with a clear error.
+or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1301 of 1301 Draft 2020-12 cases. The buffer and parallel APIs (`isValid` on raw buffers, `isValidPrepadded`, `isValidNDJSON`, `isValidParallel`, `countValid`, `batchIsValid`, `validateAndParse`) work without the addon too, answering through the same checks as `isValidJSON()`, slower than the addon: 177 ns against 92 for a small document on Node 25. In a browser, which has no `Buffer`, they throw and name the methods to use instead.
 
 Those four now agree with `validate()` on every case of the official suite, 3365 across three dialects. The native walker behind them does not handle every shape (`contains`, `unevaluatedProperties`, `patternProperties`, tuple `items`, cross-document `$ref`, a few formats), so for schemas using one of those the buffer APIs parse the bytes and answer through `validate()`; the list is in `lib/buffer-gate.js`. Typical request schemas stay on the zero-copy path. `npm test` holds the disagreement count at zero.
 
@@ -187,16 +188,16 @@ const v = new Validator(schema, { source: { path: 'schemas/user.json', content:
 const r = v.validateJSON(input)
 if (!r.valid) {
   console.error(renderPretty(r.errors))
-  // error[ATA3001]: value does not match format "email"
-  //   --> schemas/user.json:5:7
+  // error[ATA3001]: not a valid email: "not-an-email"
+  //   --> schemas/user.json:5:44
   //    |
-  //  5 |       "email": { "type": "string", "format": "email" }
-  //    |       ^^^^^^^  expected format 'email'
+  //  5 |     "email": { "type": "string", "format": "email" },
+  //    |                                            ^  expected format 'email'
   //    |
-  //   --> input, byte 23
+  //   --> input:1:24  (body.email)
   //    |
-  //  1 | {"name":"M","email":"not-an-email","age":-3}
-  //    |                     ^^^^^^^^^^^^^^  got "not-an-email"
+  //  1 | {"name":"Mert","email":"not-an-email","age":26}
+  //    |                        ^^^^^^^^^^^^^^  found "not-an-email"
   //    |
   //    = help: missing '@' and domain part
   //    = note: see https://ata-validator.com/e/ATA3001

package/index.d.ts

@@ -439,7 +439,8 @@ export interface ValidatorOptions {
    * answers `validate()`, `isValidObject()` and `validateJSON()`. For a schema
    * that arrives from outside the trust boundary. The verdict is the same on
    * every engine; the cost is not. The buffer APIs (`isValid`, `countValid`,
-   * `batchIsValid`) are native-only and unaffected.
+   * `batchIsValid`) use the native addon where it loads, which this option
+   * does not affect; without it they answer through the engine it picks.
    */
   engine?: 'auto' | 'interpreter';
 }

package/index.js

@@ -36,7 +36,7 @@ class TextRejection {
 }
 
 function installCodegenPaths (ctx) {
-  const { ABORT_EARLY_RESULT, HYBRID_TIER_CALLS, SIMDJSON_THRESHOLD, VALID_RESULT, _bindVerdict, _jsonSyntaxRejection, _mustReject, getNative, isV1Dialect, resolveSchemaByPath } = core._internals;
+  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;
   // errFn: the generated error function when it is safe, else the
   // interpreted engine, on every platform alike.
@@ -222,6 +222,11 @@ function installCodegenPaths (ctx) {
     this.validate = preprocess
       ? (data) => { preprocess(data); return run(data); }
       : run;
+    // What validate() returns for a document already known to fail, without
+    // deciding again: the lazy layer in lib/validator-core.js has its verdict
+    // 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;
   } else {
     // No hybrid factory, so the assembly needs the function itself rather
     // than a reference it can call later: build it now.
@@ -230,6 +235,7 @@ function installCodegenPaths (ctx) {
       this.validate = preprocess
         ? (data) => { preprocess(data); return safeCombinedFn(data); }
         : safeCombinedFn;
+      if (!preprocess) ctx.rejectBase = (data) => _mustReject(safeCombinedFn(data));
     } else {
       this.validate = preprocess
         ? (data) => {
@@ -237,6 +243,7 @@ function installCodegenPaths (ctx) {
             return jsFn(data) ? VALID_RESULT : errOnly(data);
           }
         : (data) => (jsFn(data) ? VALID_RESULT : errOnly(data));
+      if (!preprocess) ctx.rejectBase = errOnly;
     }
   }
   // Verbose mode: populate parentSchema, schema and data on each error, the
@@ -246,33 +253,10 @@ function installCodegenPaths (ctx) {
   // migration ended up writing by hand. Errors may be frozen, so clone
   // them with the extra fields.
   if (this._verbose) {
-    const inner = this.validate;
-    const root = this._schemaObj;
-    const { resolvePointer } = require('./lib/pointer.js');
-    this.validate = (data) => {
-      const result = inner(data);
-      if (result && !result.valid && result.errors) {
-        const enriched = result.errors.map((err) => {
-          if (!err || err.parentSchema !== undefined) return err;
-          const parentSchema = resolveSchemaByPath(root, err.schemaPath);
-          // The last segment of the schema path is the keyword that
-          // failed, so its value on the parent is that keyword's schema.
-          const sp = typeof err.schemaPath === 'string' ? err.schemaPath : '';
-          const last = sp.slice(sp.lastIndexOf('/') + 1).replace(/~1/g, '/').replace(/~0/g, '~');
-          const keywordSchema = (parentSchema !== null && typeof parentSchema === 'object' && last)
-            ? parentSchema[last]
-            : undefined;
-          return {
-            ...err,
-            parentSchema,
-            schema: keywordSchema,
-            data: resolvePointer(data, err.instancePath, undefined),
-          };
-        });
-        return { valid: false, errors: enriched };
-      }
-      return result;
-    };
+    // The verbose fields are added here, so a path around this layer would
+    // miss them.
+    ctx.rejectBase = null;
+    this.validate = _verboseWrap(this.validate, this._schemaObj);
   }
   // The verdict methods answer validate()'s question without building the
   // error list, so they run the same preprocess pass. Skipping it made the

package/lib/aot-impl.js

@@ -17,7 +17,7 @@ const { compileToJSCodegenWithErrors, compileToJSCodegen, unevalContributions }
 const { buildTargetedPositionMap } = require('./data-positions');
 const { schemaHash } = require('./schema-hash');
 const ATA_VERSION = require('./version');
-const SAFE_REGEX_SOURCE = require('./safe-regex-source');
+const { engineSource: safeRegexEngineSource } = require('./safe-regex');
 
 // Embedded verbatim in standalone modules so the output file has no runtime
 // dependency on ata-validator. ASCII fast-path plus surrogate-aware slow path.
@@ -31,21 +31,16 @@ const _CP_LEN_SOURCE = `function _cpLen(s) {
   return len;
 }`;
 
-// The linear-time regex engine, inlined verbatim into standalone output so a
-// compiled module that uses safe `pattern` matchers has no runtime dependency
-// on ata-validator. The engine source is baked into `lib/safe-regex-source.js`
-// at build time (see `scripts/regen-safe-regex-source.js`), so this path has
-// no `fs`/`path`/`__dirname` reads — safe in browser bundles too. The embed
-// strips the strict directive and CommonJS exports and adds the `__ataSafeRe`
-// alias the emitted code calls. The engine has no eval/new Function, so the
+// The linear-time regex engine, embedded in standalone modules whose patterns
+// need it so the output does not depend on ata-validator at run time. The text
+// is the engine's own function (lib/safe-regex.js), called once for the
+// `__ataSafeRe` the emitted code uses. No fs, path or __dirname, so this is
+// safe in browser bundles, and the engine has no eval or new Function, so the
 // embed is CSP-safe.
 let _safeRegexEmbed = null;
 function getSafeRegexEmbed() {
   if (_safeRegexEmbed === null) {
-    const body = SAFE_REGEX_SOURCE
-      .replace(/^'use strict'\s*\n/, '')
-      .replace(/\nmodule\.exports[^\n]*\n?/, '\n');
-    _safeRegexEmbed = body.trimEnd() + '\nconst __ataSafeRe = compileSafe;';
+    _safeRegexEmbed = 'const __ataSafeRe = (' + safeRegexEngineSource() + ')().compileSafe;';
   }
   return _safeRegexEmbed;
 }
@@ -191,6 +186,24 @@ function emitFormatDecls(closures, mode, declKW) {
 
 const { emitClone, inlineRefsForClone } = require('./clone-emit');
 
+// The schema-source frames the error function names, as `__ataSS[i]`. Each
+// is built once, frozen, from a [line, col, text index] row, with every source
+// line's text written once. Frozen, so sharing one object between reads is safe.
+function sourceFrameDecls(frames, schemaFile) {
+  if (!frames || frames.size === 0) return '';
+  const texts = [];
+  const textIndex = new Map();
+  const rows = [];
+  for (const f of frames.values()) {
+    let i = textIndex.get(f.text);
+    if (i === undefined) { i = texts.length; texts.push(f.text); textIndex.set(f.text, i); }
+    rows[f.index] = `[${f.line},${f.col},${i}]`;
+  }
+  return `const __ataSF = ${JSON.stringify(schemaFile)};\n` +
+    `const __ataSL = ${JSON.stringify(texts)};\n` +
+    `const __ataSS = [${rows.join(',')}].map((r) => Object.freeze({ file: __ataSF, line: r[0], col: r[1], text: __ataSL[r[2]] }));\n`;
+}
+
 function toStandaloneModule(validator, opts) {
   assertEmittable(validator, 'toStandaloneModule');
   validator._ensureCompiled();
@@ -205,15 +218,27 @@ function toStandaloneModule(validator, opts) {
 
   let errCore = '';
   let jsErrFn = null;
+  const sourceFrames = new Map();
   if (!abortEarly) {
     jsErrFn = compileToJSCodegenWithErrors(
       typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
       null,
       validator._userFormats,
-      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile } : null,
+      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames } : null,
     );
     const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
-    if (errSrc) {
+    if (errSrc && jsErrFn._errFactory) {
+      // The helpers (patterns, name sets, definition and branch functions) are
+      // built once, not on every call. With $defs the
+      // cycle guard's state sits beside them, so a call made while one is
+      // running takes a function from a fresh factory call.
+      // Built on the first error read rather than at import, so a page that
+      // only ever accepts pays nothing for them at load.
+      const fac = jsErrFn._errFactory;
+      errCore = jsErrFn._errGuarded
+        ? `const _mkErr = function() {\n  ${fac}\n};\nlet _errMain = null;\nlet _errBusy = false;\nconst errFn = function(d, _all) { if (_errBusy) return _mkErr()(d, _all); if (_errMain === null) _errMain = _mkErr(); _errBusy = true; try { return _errMain(d, _all); } finally { _errBusy = false; } };\n`
+        : `const _mkErr = function() {\n  ${fac}\n};\nlet _errMain = null;\nconst errFn = function(d, _all) { return (_errMain || (_errMain = _mkErr()))(d, _all); };\n`;
+    } else if (errSrc) {
       errCore = `const errFn = function(d, _all) {\n  ${errSrc}\n};\n`;
     } else if (opts && typeof opts.onWarning === 'function') {
       // The caller asked for error detail and is not getting it: the error
@@ -239,7 +264,7 @@ function toStandaloneModule(validator, opts) {
   // entirely so size budgets and grep-based "is this source-mapped?" checks
   // both work.
   const schemaSourceConst = (source && schemaFile)
-    ? `const __ATA_SCHEMA_SOURCE__ = ${JSON.stringify({ file: schemaFile })};\n`
+    ? `const __ATA_SCHEMA_SOURCE__ = ${JSON.stringify({ file: schemaFile })};\n` + sourceFrameDecls(sourceFrames, schemaFile)
     : '';
 
   // Serialize closure vars referenced in _fn body: regex, sub-validators, sets.

package/lib/buffer-gate.js

@@ -122,14 +122,13 @@ function toText(input, name) {
   throw new TypeError(`${name}() requires a Buffer, Uint8Array, or string. For parsed objects, use isValidObject().`);
 }
 
-// Replaces the instance's buffer APIs with versions that parse and call
-// validate(). Installed after compilation, so `validator.validate` is final.
+// Replaces the instance's buffer APIs with versions that decode the bytes and
+// ask isValidJSON(), which answers as validate() does on the parsed value and
+// reads text the scanner covers without parsing it (a small document went from
+// 350 to 155 ns without the addon). Its own native route is behind this same
+// gate, so a schema routed here never reaches the walker through it.
 function installSlowBufferApis(validator) {
-  const isValidText = (text) => {
-    let value;
-    try { value = JSON.parse(text); } catch { return false; }
-    return validator.validate(value).valid;
-  };
+  const isValidText = (text) => validator.isValidJSON(text);
   validator.isValid = (input) => isValidText(toText(input, 'isValid'));
   validator.isValidPrepadded = (paddedBuffer, jsonLength) =>
     isValidText(Buffer.from(paddedBuffer.buffer, paddedBuffer.byteOffset, jsonLength).toString('utf8'));

package/lib/enrich-error.js

@@ -233,8 +233,10 @@ function enrich (rawErr, opts) {
   if ('schema' in rawErr) out.schema = rawErr.schema;
 
   // oneOf/anyOf collapse: preserve the nested branch errors so the pretty
-  // renderer can surface the closest variant's diagnostics.
-  if (rawErr.branchErrors) out.branchErrors = rawErr.branchErrors;
+  // renderer can surface the closest variant's diagnostics. They are enriched
+  // like any other error: passed through raw, they carried whatever the engine
+  // that answered wrote, the generator's internal ordering key included.
+  if (rawErr.branchErrors) out.branchErrors = rawErr.branchErrors.map((b) => enrich(b, data !== undefined ? { data } : null));
 
   if (positions && positions[path]) {
     const p = positions[path];