ata-validator 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 1.24.0 - 2026-09-16
+
+### Added
+
+- A schema-directed scanner: `isValidJSON()` answers the verdict from the JSON text without building the document. Parsing is about three quarters of the cost of a request that only needs yes or no, and a rejection now stops at the byte that caused it. The scanner compiles per schema, on the codegen path only, after 64 calls (generating one costs about 20 µs, so a caller that checks one document never pays), and it declines anything outside its supported core: `type`, `properties`, `required`, `additionalProperties`, `items`, `prefixItems`, the length, size and range keywords, `pattern`, `format`, `const`, `enum`, local `$ref` (inlined, acyclic, no base-changing keywords below the root), `allOf` (merged, with the `additionalProperties` cross-branch rule written out in full), and `unevaluated*` where it is provably a synonym for `additionalProperties`/`items`. Whatever it cannot answer it declines at compile time or bails from at runtime, and the parse path takes over unchanged. `tests/test_scanner_differential.js` holds the scanner and `validate()` to the same verdict on the same text: 413,130 comparisons over the official suite, a malformed-JSON corpus and generated corruptions, zero disagreements, and the count must stay at zero.
+  - Cross-process medians against the same call forced through `JSON.parse`: accepted documents 1.19x to 1.43x by size; rejection at the first element 37x at 4 KB and 385x at 41 KB.
+  - Generated config schemas are first-class: up to 4096 properties per node, and past 48 names the dispatch is a rolling hash accumulated during the key scan, one lookup in a Map passed outside the source, one `startsWith` to confirm, bodies shared per distinct subschema, and an in-order fast path for machine-written JSON that resynchronises across omitted optional keys. A 26.6 KB config with 1300 declared properties: 136.7 µs by parse-and-validate, 43.8 µs by scan.
+  - `isValidJSON` also remembers the last (text, verdict) pair, since the verdict is a pure function of the text: a drift monitor re-reading an unchanged file answers in 0.44 µs by native string compare. Withheld when user formats or custom keywords are present, since user functions may not be pure.
+- Strict mode covers all four cases from issue #44: unknown keywords (with a spelling suggestion), unresolvable local `$ref`s, keywords the node's own `type` makes inert (`minimum` on a string can never fire), and `required` names nothing can satisfy (`additionalProperties: false` with the name absent from `properties`). `ata compile --strict-schema` and `build({ strictSchema: true })` run the same checks at build time and refuse to emit a module from a schema that fails them.
+
+### Fixed
+
+- An AOT module that cannot carry error detail says so. `toStandaloneModule` with error detail requested builds the error function from the error generator, which declines some schemas, `unevaluated*` among them; the runtime validator falls back to the interpreted engine there, but a standalone module has nothing to fall back to, so it shipped with an exact verdict and a single ATA9000 stub for every failure, silently. The module still ships, since the verdict is exact and validating the rare failing document with the runtime `Validator` is a legitimate pattern, but the degradation is loud in every layer: `onWarning` on the emitter, a NOTE in the module header, a `warnings` list in the `build()` report, a printed warning from `ata compile`, and a refused build under `--strict`. Found by a gateway team that lost their per-field startup errors to it.
+
 ## 1.23.0 - 2026-09-16
 
 ### Added

package/bin/ata.js

@@ -38,6 +38,10 @@ Build options:
   --cache-file <path>     Cache file for incremental builds (default: cache disabled)
   --max-size <bytes>      Fail build if any compiled module exceeds this gzipped size
   --strict                Treat any AOT-incompatible schema as a build error (default: skip + warn)
+  --strict-schema         Fail the build on schema authoring mistakes: unknown
+                          keywords (with a spelling suggestion), keywords the
+                          node's type makes inert, unresolvable local $refs,
+                          and required names nothing can satisfy
   --watch                 Re-emit on schema change (Ctrl-C to exit)
   --no-types              Skip .d.mts/.d.cts emission alongside compiled modules
   --source                Embed schema source map (default in development)
@@ -80,6 +84,7 @@ function parseArgs(argv) {
     if (a === '--abort-early') { out.opts.abortEarly = true; continue; }
     if (a === '--check') { out.opts.check = true; continue; }
     if (a === '--strict') { out.opts.strict = true; continue; }
+    if (a === '--strict-schema') { out.opts.strictSchema = true; continue; }
     if (a === '--out-dir') { out.opts.outDir = argv[++i]; continue; }
     if (a === '--suffix') { out.opts.suffix = argv[++i]; continue; }
     if (a === '--cache-file') { out.opts.cacheFile = argv[++i]; continue; }
@@ -180,6 +185,19 @@ function cmdCompile(args) {
     process.exit(1);
   }
 
+  // The build is where an authoring mistake is cheapest to stop: a typo like
+  // maxLenght compiles into a module that simply lacks the rule, and nobody
+  // revisits a compiled module. Findings fail the compile, with the path and
+  // the suggested spelling.
+  if (args.opts.strictSchema) {
+    const { checkSchemaStrict } = require('../lib/strict-check');
+    const problems = checkSchemaStrict(schema, {});
+    if (problems.length > 0) {
+      for (const x of problems) reportCompileError(input, `strict mode: ${x.message} at ${x.path}`);
+      process.exit(1);
+    }
+  }
+
   const { Validator } = require('..');
   const aot = require('../lib/aot');
   let v;
@@ -200,7 +218,15 @@ function cmdCompile(args) {
     }
   }
   const schemaFile = path.relative(process.cwd(), input) || input;
-  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile });
+  const compileWarnings = [];
+  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onWarning: (w) => compileWarnings.push(w) });
+  if (compileWarnings.length > 0) {
+    if (args.opts.strict) {
+      for (const w of compileWarnings) reportCompileError(input, w);
+      process.exit(1);
+    }
+    for (const w of compileWarnings) process.stderr.write(`ata: warning: ${input}: ${w}\n`);
+  }
   if (!src) {
     reportCompileError(input, 'schema is too complex for standalone compilation');
     process.exit(1);

package/index.js

@@ -933,6 +933,8 @@ class Validator {
     // to attach dataFrame entries to each enriched error.
     this._posCache = null; // created by _pos() on first use, only the JSON text path needs it
     this._lastRawInput = null;
+    // undefined: not built yet. null: this schema has no scanner.
+    this._scanner = undefined;
 
     // Public methods start as memoized accessors on the prototype; nothing is
     // allocated per instance until one is first read. See _defineLazyMethod
@@ -1426,6 +1428,23 @@ class Validator {
             return verdictFromText(jsonStr);
           }
         : verdictFromText;
+
+      // A schema-directed scanner answers the verdict from the JSON text
+      // without building the document. Parsing is around three quarters of the
+      // cost of a real request, and a caller that only wants yes or no should
+      // not pay it; a rejection can also stop at the byte that caused it
+      // instead of parsing the rest of a document that is already refused.
+      //
+      // It is wired only where the verdict IS the answer. On a path that has
+      // to produce errors, scanning an invalid document is work thrown away,
+      // so those keep parsing. `abortEarly` has no errors to produce, so it
+      // counts as a verdict path.
+      //
+      // Not wired when a preprocess pass is configured: coercion, removal and
+      // defaults rewrite the document before it is judged, and the scanner
+      // reads what arrived. The compiler declines any schema it cannot answer
+      // and a compiled scanner returns BAIL for a document shape it cannot
+      // answer, and then the parse path below takes over unchanged.
       // validateAndParse: parse the JSON, then validate. Pure JS (JSON.parse +
       // validate) so it works with or without the native addon and in browsers.
       {
@@ -1799,6 +1818,83 @@ class Validator {
       const { bufferNeedsSlowPath, installSlowBufferApis } = require('./lib/buffer-gate.js');
       if (bufferNeedsSlowPath(schemaObj, this._schemaMap, this._keywords)) installSlowBufferApis(this);
     }
+    // Installed after the buffer gate on purpose: the gate replaces
+    // isValidJSON for schemas whose shapes the native walker gets wrong,
+    // unevaluatedProperties among them, and the scanner wiring has to wrap
+    // whatever answers last or a gated schema silently loses its scanner.
+    if (this._jsFn && !this._preprocess) {
+        const self = this;
+        // Generating a scanner costs about 20 microseconds, measured, and it
+        // saves from around 85 nanoseconds on a small accepted document to
+        // several microseconds on a rejected one. Building it on the first
+        // call would therefore be a straight loss for a caller that checks one
+        // document and exits, so it is built once a caller has asked often
+        // enough that it is plainly doing this in a loop. A server passes the
+        // line during warm-up and never sees it.
+        const SCAN_AFTER = 64;
+        let calls = 0;
+        // undefined: not built. null: this schema has no scanner. Passing true
+        // builds it now, which is how the differential test reaches it.
+        this._ensureScanner = (now) => {
+          if (self._scanner === undefined) {
+            if (!now && ++calls < SCAN_AFTER) return undefined;
+            const built = require('./lib/scan-compiler').compileScanner(schemaObj, { userFormats: self._userFormats });
+            self._scanner = built ? built.scan : null;
+          }
+          return self._scanner;
+        };
+        const byParsing = this.isValidJSON;
+        // The verdict is a pure function of the text, and the caller a
+        // gateway or a drift monitor keeps asking about is usually the same
+        // text: a config file re-read on a timer, a heartbeat body. One
+        // remembered (text, verdict) pair answers that case with a native
+        // string compare, which is a memcmp, instead of a scan. Withheld when
+        // user formats or custom keywords are present, since those are user
+        // functions and nothing guarantees they are pure.
+        const memoizable = !self._userFormats && !self._usesKeywords;
+        let _memoText = null;
+        let _memoVerdict = false;
+        this.isValidJSON = (jsonStr) => {
+          const scan = self._ensureScanner();
+          if (scan === undefined) return byParsing(jsonStr);
+          if (scan === null) { self.isValidJSON = byParsing; return byParsing(jsonStr); }
+          self.isValidJSON = memoizable
+            ? (text) => {
+                if (typeof text !== 'string') return byParsing(text);
+                if (text === _memoText) return _memoVerdict;
+                const r = scan(text);
+                const verdict = r === -1 ? byParsing(text) : r === 1;
+                _memoText = text;
+                _memoVerdict = verdict;
+                return verdict;
+              }
+            : (text) => {
+                if (typeof text !== 'string') return byParsing(text);
+                const r = scan(text);
+                if (r === -1) return byParsing(text);
+                return r === 1;
+              };
+          return self.isValidJSON(jsonStr);
+        };
+        if (options.abortEarly) {
+          const validateByParsing = this.validateJSON;
+          this.validateJSON = (jsonStr) => {
+            const scan = self._ensureScanner();
+            if (scan === undefined) return validateByParsing(jsonStr);
+            if (scan === null) { self.validateJSON = validateByParsing; return validateByParsing(jsonStr); }
+            self.validateJSON = (text) => {
+              if (typeof text === 'string') {
+                const r = scan(text);
+                if (r === 1) return VALID_RESULT;
+                if (r === 0) return ABORT_EARLY_RESULT;
+              }
+              return validateByParsing(text);
+            };
+            return self.validateJSON(jsonStr);
+          };
+        }
+      }
+
 
     // Save to identity cache for ultra-fast reuse with same schema object.
     // Only an instance built without options may answer a later

package/lib/aot-build.js

@@ -94,6 +94,7 @@ async function build(opts) {
   const cached = [];
   const skipped = [];
   const failed = [];
+  const warnings = [];
 
   for (const input of inputs) {
     try {
@@ -126,6 +127,18 @@ async function build(opts) {
         continue;
       }
       const schema = parseSchemaFile(input);
+      // The build is where an authoring mistake is cheapest to stop: a typo
+      // like maxLenght compiles into a validator that simply lacks the rule,
+      // and a compiled module fails even more quietly than a runtime one,
+      // since nobody ever revisits it. Findings fail the input's build.
+      if (opts.strictSchema) {
+        const { checkSchemaStrict } = require('./strict-check');
+        const problems = checkSchemaStrict(schema, {});
+        if (problems.length > 0) {
+          failed.push({ input, error: problems.map((x) => `strict mode: ${x.message} at ${x.path}`).join('; ') });
+          continue;
+        }
+      }
       const v = new Validator(schema);
       const source = resolveSourceDefault(opts);
       let sourceMap = null;
@@ -138,6 +151,7 @@ async function build(opts) {
         }
       }
       const schemaFile = path.relative(process.cwd(), input) || input;
+      const inputWarnings = [];
       const src = aot.toStandaloneModule(v, {
         format,
         abortEarly: !!opts.abortEarly,
@@ -145,7 +159,15 @@ async function build(opts) {
         sourceMap,
         schemaFile,
         formatMode: opts.formatMode,
+        onWarning: (w) => inputWarnings.push(w),
       });
+      if (inputWarnings.length > 0) {
+        if (opts.strict) {
+          failed.push({ input, error: inputWarnings.join('; ') });
+          continue;
+        }
+        for (const w of inputWarnings) warnings.push({ input, warning: w });
+      }
       if (!src) {
         const reason = 'schema is not AOT-compatible (toStandaloneModule returned null)';
         if (opts.strict) failed.push({ input, error: reason });
@@ -190,12 +212,12 @@ async function build(opts) {
 
   if (opts.check) {
     const staleCount = inputs.length - cached.length;
-    return { compiled: [], cached, skipped, failed, staleCount };
+    return { compiled: [], cached, skipped, failed, warnings, staleCount };
   }
 
   writeCache(opts.cacheFile, newCache);
 
-  return { compiled, cached, skipped, failed };
+  return { compiled, cached, skipped, failed, warnings };
 }
 
 async function watch(opts, onReport) {

package/lib/aot-impl.js

@@ -269,6 +269,16 @@ function toStandaloneModule(validator, opts) {
     const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
     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
+      // generator declined this schema (unevaluated* and a few other shapes),
+      // and a standalone module has no interpreted engine to fall back to the
+      // way the runtime validator does. The module still ships, with the
+      // verdict exact, but every failure reports the single ATA9000 stub.
+      // Silence here cost a user a debugging session; hence the channel.
+      opts.onWarning(
+        'error detail could not be generated for this schema; the module reports failures as the single ATA9000 abort-early error. The verdict is unaffected. For detailed errors, validate failing documents with the runtime Validator.'
+      );
     }
   }
 
@@ -379,9 +389,12 @@ function toStandaloneModule(validator, opts) {
     ? `export { ${names}${parseAlias} };\nexport default { ${names}${parseProp} };\n`
     : `module.exports = { ${names}${parseProp} };\nmodule.exports.default = module.exports;\n`;
 
+  const degradedNote = (!abortEarly && !errCore)
+    ? '// NOTE: error detail was requested but could not be generated for this\n// schema; failures report the single ATA9000 abort-early error. The verdict\n// is exact. Validate failing documents with the runtime Validator for detail.\n'
+    : '';
   return `// Auto-generated by ata-validator — do not edit.
 // Schema is embedded; runtime has zero dependency on ata-validator.
-'use strict';
+${degradedNote}'use strict';
 ${_CP_LEN_SOURCE}
 ${safeRePrelude(jsFn, jsErrFn)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
 const ABORT = Object.freeze({