ata-validator 1.8.2 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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.10.0 - 2026-08-30
+
+### Performance
+
+- The code generator takes shapes it used to decline for no correctness reason: boolean subschemas in `items`, `properties`, `patternProperties`, `dependentSchemas`, `propertyNames`, `allOf`, `anyOf`, `not`, `contains` and `if`/`then`/`else`, recursive `#/$defs/` references as named functions, and `additionalProperties` as a schema alongside composition or `patternProperties`. Each lands in all three generators and the closure path, held to the interpreter by `tests/test_codegen_edge_shapes.js` and the entry-point agreement test over the whole official suite. Every suite group that moved off the interpreter got faster, 31 of 31 on draft 2020-12 and 28 of 28 on draft 7, summed per-group time down 70 percent. The suite-wide figure, measured interleaved against the previous release in one process, did not move outside that measurement's noise; `benchmark/verdict-bench.md` has the numbers and says why.
+- `date` and `ipv4` format checks read the string once with no regular expression and no allocation: 45.7 to 14.2 ns and 54.5 to 27.1 ns on a valid value, interleaved medians. Fuzzed against the previous forms with 0 mismatches; `tests/test_formats_single_pass.js` keeps it that way.
+
+### Fixed
+
+- A key matched only by the second of two `patternProperties` entries, alongside `additionalProperties: false`, was rejected: the generated key loop returned at the first pattern that missed. Found while rewriting that loop; covered by the edge-shape test.
+- A declared property that also matched a `patternProperties` entry skipped the pattern's schema in the generated code when `additionalProperties` was a schema. The suite's own interaction case caught it the moment the shape was allowed to compile.
+
+## 1.9.0 - 2026-08-28
+
+### Errors
+
+- Rendered diagnostics now say where the problem is. Every `renderPretty` and `renderCompact` block carries the JSON path, and a source frame with a caret on the failing token when one can be built faithfully: from the text on the `validateJSON` path, or from the object when the renderer is handed `{ data }`. Object-input frames are reconstructed by re-serializing the value and the output says so once, because the line numbers refer to that reconstruction. No frame is reconstructed under `coerceTypes`, `removeAdditional` or a schema with `default` values, since the object in hand is not what the caller sent; the output names the option instead.
+- Headlines state the observation rather than the rule: `expected integer, found string` in place of `must be integer`. Two `additionalProperties` violations no longer render as identical blocks; the property name is in the headline. A composition failure with a `const` discriminator names it, `no variant matches kind "circle"`, anchors inside the closest branch, and its branch notes read `minimum: expected ≥0, found -1`.
+- A property typed `nmae` where `name` was required renders as one diagnostic with `did you mean "name"?` instead of two. The correlation requires that no other missing or extra key in the same object is equally close; on a tie nothing is merged. Both errors stay in the array and point at each other through the new `related` field, and the footer reads `8 schema violations in input, shown as 7 diagnostics` so the count never drifts from `errors.length`.
+- Diagnostics are ordered by document position, with cause before effect only as a tie-break within one container. Carets are clamped to the line they sit under; a root-level error used to draw one the width of the whole document.
+- Under `richErrors` (the default) errors gain `detail`, `related`, `anchor` and `rank`. Existing fields, array order and array length are unchanged; `richErrors: false` still returns the v0.14 shape. `useDefaults`, on by default, is now documented.
+- Measured on a ten-case corpus scored on four questions per diagnostic (says where, states what was found, distinguishable from its neighbours, offers a way forward): 3 of 60 before, 58 of 58 after, and `tests/test_diagnostics_score.js` holds the floor at 95%. Cost on the reject path when `.errors` is read, master against this change on the same machine: a one-error document 330 to 395 ns, a seven-error document with a typo pair 2.45 to 2.95 µs. `validate().valid` is unchanged at 5 ns. Fastify's own suite through fastify-ata stays at 178 of 184.
+
 ## 1.8.2 - 2026-08-28
 
 ### Fixed

package/index.js

@@ -992,6 +992,13 @@ class Validator {
               };
     }
     this._applyDefaults = preprocess;
+    // Whether validate() can change the caller's object before the verdict.
+    // This is a capability, not an option: `useDefaults` is on by default, but
+    // buildDefaultsApplier returns null when the schema declares no defaults,
+    // so a plain schema is genuinely non-mutating. The renderers refuse to
+    // synthesize a frame when this is true, because a frame built from mutated
+    // data would show the reader a value they never sent.
+    this._mutatesInput = !!(preprocess || options.coerceTypes || options.removeAdditional);
     this._preprocess = preprocess;
 
     // Detect if schema is "selective" -- doesn't recurse into arrays/deep objects.
@@ -1426,6 +1433,16 @@ class Validator {
                       schemaFile: self._source ? self._source.path : undefined,
                     }))
                   : raw;
+                // 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 below, and a renderer given `{ data }` builds frames for
+                // object input on request.
               }
               return cached;
             },
@@ -1451,21 +1468,34 @@ class Validator {
           if (result && !result.valid && result.errors && result.errors.length) {
             // If errors came from the inner path that already ran through the
             // wrapped this.validate (codegen jsonValidateFn -> validate path),
-            // they may already be enriched. Detect by presence of `code`.
+            // they may already be enriched. Detect by presence of `docUrl`:
+            // only enrich() sets it. `code` is not a safe signal because
+            // branch-collapse attaches codes to raw errors, and detecting on
+            // it left every collapsed oneOf/anyOf error unenriched on the
+            // text path.
             const first = result.errors[0];
-            if (!first || !first.code) {
+            // Re-parse the input once so the enrich pass can pluck `received`
+            // and feed the suggestion engine (required-typo, format hints,
+            // coercion nudges all need the live value tree), and so the
+            // diagnostic payload carries the data on both paths below.
+            let parsedData;
+            try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
+            if (!first || !first.docUrl) {
               const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
-              // Re-parse the input once so the enrich pass can pluck `received`
-              // and feed the suggestion engine (required-typo, format hints,
-              // coercion nudges all need the live value tree).
-              let parsedData;
-              try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
               const enriched = result.errors.map((e) => enrich(e, {
                 data: parsedData,
                 positions,
                 schemaPositions: this._schemaPositions,
                 schemaFile: this._source ? this._source.path : undefined,
               }));
+              if (enriched.length > 1) attachRelated(enriched);
+              attachDiagnosticSource(enriched, {
+                data: parsedData,
+                text: jsonStr,
+                positions,
+                schema: this._schemaObj,
+                mutatesInput: this._mutatesInput === true,
+              });
               if (positions) this._posCache.reset();
               this._lastRawInput = null;
               return { valid: false, errors: enriched };
@@ -1482,6 +1512,13 @@ class Validator {
               }
               this._posCache.reset();
             }
+            if (result.errors.length > 1) attachRelated(result.errors);
+            attachDiagnosticSource(result.errors, {
+              data: parsedData,
+              text: jsonStr,
+              schema: this._schemaObj,
+              mutatesInput: this._mutatesInput === true,
+            });
           }
           this._lastRawInput = null;
           return result;
@@ -1945,6 +1982,26 @@ function _walkPointer (root, pointer) {
 // inflate the gzipped bundle beyond the size budget). Consumers who want
 // suggestions pass the error array through this helper after validation.
 // AOT errors don't carry `received`, so we re-derive it from `data` here.
+const { setDiagnosticSource } = require('./lib/diagnostic-source');
+const attachDiagnosticSource = setDiagnosticSource;
+
+// 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('./lib/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;
+}
+
 function attachSuggestions (errors, data) {
   if (!errors) return errors;
   for (const e of errors) {
@@ -1961,6 +2018,9 @@ function attachSuggestions (errors, data) {
     const s = suggestFor(probe, data);
     if (s) e.suggestion = s;
   }
+  // AOT modules import nothing, so this is their only route to a frame. The
+  // caller holds the original object and ran no preprocessing through here.
+  attachDiagnosticSource(errors, { data, mutatesInput: false });
   return errors;
 }
 

package/lib/correlate.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const { levenshtein } = require('./levenshtein');
+
+const MAX_DISTANCE = 2;
+
+/**
+ * Pair a `required` error naming a missing property with an
+ * `additionalProperties` error naming an extra property, when the two names
+ * are close enough to be one typo and nothing else in the same container is
+ * equally close.
+ *
+ * The tie checks are the point. `suggestRequiredTypo` in lib/suggestions.js
+ * takes the first key within distance 2 and does not check for ties, which is
+ * fine for a hint appended to an error that stands on its own. It is not fine
+ * as a reason to present two errors as one problem: an ambiguous pairing would
+ * tell the reader a confident story about the wrong key.
+ *
+ * Nothing is deleted. The result is a symmetric index map that callers may use
+ * to group; every error stays in the array.
+ *
+ * @param {Array} errors enriched or raw validation errors
+ * @returns {Map<number, number>|null} symmetric index pairs, null when there are none
+ */
+function correlateTypos (errors) {
+  if (!Array.isArray(errors) || errors.length < 2) return null;
+
+  // Most rejections have no candidate pair at all. Find that out with one
+  // pass over the keywords before allocating anything.
+  let sawMissing = false;
+  let sawExtra = false;
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    if (!e) continue;
+    if (e.keyword === 'required') sawMissing = true;
+    else if (e.keyword === 'additionalProperties') sawExtra = true;
+    if (sawMissing && sawExtra) break;
+  }
+  if (!sawMissing || !sawExtra) return null;
+
+  const out = new Map();
+
+  // Bucket by container pointer. A missing key in one object has nothing to do
+  // with an extra key in another.
+  const byContainer = new Map();
+  for (let i = 0; i < errors.length; i++) {
+    const e = errors[i];
+    if (!e || !e.params) continue;
+    const missing = e.keyword === 'required' ? e.params.missingProperty : undefined;
+    const additional = e.keyword === 'additionalProperties' ? e.params.additionalProperty : undefined;
+    if (typeof missing !== 'string' && typeof additional !== 'string') continue;
+    const key = e.instancePath != null ? e.instancePath : (e.path || '');
+    let bucket = byContainer.get(key);
+    if (!bucket) { bucket = { missing: [], extra: [] }; byContainer.set(key, bucket); }
+    if (typeof missing === 'string') bucket.missing.push({ index: i, name: missing });
+    else bucket.extra.push({ index: i, name: additional });
+  }
+
+  for (const bucket of byContainer.values()) {
+    if (bucket.missing.length === 0 || bucket.extra.length === 0) continue;
+
+    // Full distance table for this container. Sizes here are the number of
+    // wrong keys in one object, so this stays small in practice.
+    const dist = [];
+    for (let m = 0; m < bucket.missing.length; m++) {
+      dist.push([]);
+      for (let x = 0; x < bucket.extra.length; x++) {
+        const d = levenshtein(bucket.missing[m].name, bucket.extra[x].name, MAX_DISTANCE);
+        dist[m].push(d);
+      }
+    }
+
+    for (let m = 0; m < bucket.missing.length; m++) {
+      // Best extra key for this missing key, and whether it is unique.
+      let bestX = -1;
+      let bestD = Infinity;
+      let tied = false;
+      for (let x = 0; x < bucket.extra.length; x++) {
+        const d = dist[m][x];
+        if (d < bestD) { bestD = d; bestX = x; tied = false; }
+        else if (d === bestD && d !== Infinity) tied = true;
+      }
+      if (bestX === -1 || tied) continue;
+      if (!(bestD > 0 && bestD <= MAX_DISTANCE)) continue;
+
+      // And the same question from the other side: is this missing key the
+      // unambiguous best match for that extra key?
+      let backM = -1;
+      let backD = Infinity;
+      let backTied = false;
+      for (let m2 = 0; m2 < bucket.missing.length; m2++) {
+        const d = dist[m2][bestX];
+        if (d < backD) { backD = d; backM = m2; backTied = false; }
+        else if (d === backD && d !== Infinity) backTied = true;
+      }
+      if (backTied || backM !== m) continue;
+
+      out.set(bucket.missing[m].index, bucket.extra[bestX].index);
+      out.set(bucket.extra[bestX].index, bucket.missing[m].index);
+    }
+  }
+
+  return out.size === 0 ? null : out;
+}
+
+module.exports = { correlateTypos };

package/lib/data-positions.js

@@ -52,7 +52,7 @@ function buildDataPositionMap (input) {
     return '/' + path.map(escapePtr).join('/');
   }
 
-  function walk (path) {
+  function walk (path, keySpan) {
     skipWs();
     if (i >= n) return;
     const start = i;
@@ -66,11 +66,22 @@ function buildDataPositionMap (input) {
         if (text.charCodeAt(i) === 0x7d) { i++; break; }
         if (text.charCodeAt(i) === 0x2c) { i++; continue; }
         skipWs();
+        // Record the key token before consuming it. The caret for an error
+        // that names a property belongs on the property, not on the value and
+        // not on the enclosing object.
+        const keyStart = i;
+        const keyPos = offsetToLineCol(keyStart);
         const key = readString();
+        const span = {
+          keyOffset: keyStart,
+          keyLength: i - keyStart,
+          keyLine: keyPos.line,
+          keyCol: keyPos.col,
+        };
         skipWs();
         if (text.charCodeAt(i) !== 0x3a) throw new Error('expected ":" at offset ' + i);
         i++;
-        walk(path.concat([key]));
+        walk(path.concat([key]), span);
       }
     } else if (ch === 0x5b) {
       i++;
@@ -93,7 +104,14 @@ function buildDataPositionMap (input) {
     }
 
     const length = i - start;
-    map[pointerOf(path)] = { byteOffset: start, length, line: pos.line, col: pos.col, text: pos.text };
+    const entry = { byteOffset: start, length, line: pos.line, col: pos.col, text: pos.text };
+    if (keySpan) {
+      entry.keyOffset = keySpan.keyOffset;
+      entry.keyLength = keySpan.keyLength;
+      entry.keyLine = keySpan.keyLine;
+      entry.keyCol = keySpan.keyCol;
+    }
+    map[pointerOf(path)] = entry;
   }
 
   if (text.charCodeAt(0) === 0xfeff) i = 1;

package/lib/diagnose.js

@@ -0,0 +1,312 @@
+'use strict';
+
+const { correlateTypos } = require('./correlate');
+const { buildDataPositionMap } = require('./data-positions');
+const { pathToDotted } = require('./render-shared');
+const { reprValue, expectedFor } = require('./enrich-error');
+
+const MAX_SYNTHESIZED_BYTES = 256 * 1024;
+
+/**
+ * Turn a validation error array into presentation-ready diagnostics.
+ *
+ * Pure: no I/O, no ANSI, no terminal width, deterministic for a given input.
+ * That is deliberate. The merge below is the one place in this library that
+ * can present two problems as one, so it has to be provable as data rather
+ * than by grepping terminal output.
+ *
+ * @param {Array} errors validation errors, enriched or raw
+ * @param {{text?: string, data?: any, positions?: object, schema?: object, mutatesInput?: boolean}} [source]
+ * @returns {Array} diagnostics
+ */
+function toDiagnostics (errors, source) {
+  if (!Array.isArray(errors) || errors.length === 0) return [];
+  const src = source || {};
+
+  const resolved = resolveFrames(src);
+  const pairs = correlateTypos(errors);
+
+  const diagnostics = [];
+  const consumed = new Set();
+
+  for (let i = 0; i < errors.length; i++) {
+    if (consumed.has(i)) continue;
+    const e = errors[i];
+    if (!e) continue;
+
+    const partner = pairs === null ? undefined : pairs.get(i);
+    if (partner !== undefined && !consumed.has(partner)) {
+      consumed.add(i);
+      consumed.add(partner);
+      diagnostics.push(mergedDiagnostic(errors, i, partner, resolved, src));
+      continue;
+    }
+
+    diagnostics.push(singleDiagnostic(e, i, resolved, src));
+  }
+
+  diagnostics.sort((a, b) => {
+    if (a.sortPos !== b.sortPos) return a.sortPos - b.sortPos;
+    if (a.rank !== b.rank) return a.rank - b.rank;
+    return a.pointer < b.pointer ? -1 : a.pointer > b.pointer ? 1 : 0;
+  });
+
+  for (const d of diagnostics) delete d.sortPos;
+  return diagnostics;
+}
+
+// Resolve one position map for the whole call, not one per error.
+function resolveFrames (src) {
+  const none = { positions: null, synthesized: false, refusal: null };
+  if (src.positions) return { positions: src.positions, synthesized: false, refusal: null };
+
+  if (src.text != null) {
+    try {
+      return { positions: buildDataPositionMap(src.text), synthesized: false, refusal: null };
+    } catch {
+      return none;
+    }
+  }
+
+  if (src.data === undefined) return none;
+
+  if (src.mutatesInput) {
+    // The object in hand is not what the caller sent. Drawing a caret under a
+    // coerced value or an injected default would be output that is wrong and
+    // draws no complaint, which is the failure mode this library treats as the
+    // worst one. Say why instead.
+    return {
+      positions: null,
+      synthesized: false,
+      refusal: 'no frame; the value was modified in place before validation (coerceTypes, useDefaults or removeAdditional)',
+    };
+  }
+
+  let text;
+  try {
+    text = JSON.stringify(src.data, null, 2);
+  } catch {
+    return none;
+  }
+  if (typeof text !== 'string') return none;
+  if (text.length > MAX_SYNTHESIZED_BYTES) {
+    // The string cannot be measured without being built. It is built, measured
+    // and dropped; there is no way to skip the allocation and still know.
+    return { positions: null, synthesized: false, refusal: 'no frame; the value is larger than 256 KB' };
+  }
+  try {
+    return { positions: buildDataPositionMap(text), synthesized: true, refusal: null };
+  } catch {
+    return none;
+  }
+}
+
+function frameFor (err, resolved) {
+  if (!resolved.positions) return frameFromError(err);
+  const path = err.instancePath != null ? err.instancePath : (err.path || '');
+  const named = (err.params && (err.params.additionalProperty || err.params.unevaluatedProperty)) || null;
+  const hit = (named && resolved.positions[path + '/' + named]) || resolved.positions[path];
+  if (!hit) return null;
+
+  // A caret on the key token when the error names a property, on the value
+  // otherwise. Never wider than the line it is drawn under.
+  const useKey = named != null && hit.keyOffset !== undefined;
+  const col = useKey ? hit.keyCol : hit.col;
+  const rawLen = useKey ? hit.keyLength : hit.length;
+  const lineLen = (hit.text || '').length;
+  const length = Math.max(1, Math.min(rawLen || 1, Math.max(1, lineLen - col + 1)));
+
+  return {
+    line: useKey ? hit.keyLine : hit.line,
+    col,
+    length,
+    text: hit.text,
+    spans: rawLen > length,
+    synthesized: resolved.synthesized,
+  };
+}
+
+// No position map in hand, but the error itself may carry one: validateJSON
+// attaches `dataFrame` and `anchor` at enrichment time, and errors handed
+// over from another process or a fixture arrive with only those.
+function frameFromError (err) {
+  const df = err.dataFrame;
+  if (!df || typeof df.line !== 'number') return null;
+  const a = err.anchor;
+  const named = (err.params && (err.params.additionalProperty || err.params.unevaluatedProperty)) || null;
+  const useKey = named != null && a && a.keyLine !== undefined;
+  const col = useKey ? a.keyCol : df.col;
+  const rawLen = useKey ? a.keyLength : df.length;
+  const lineLen = (df.text || '').length;
+  const length = Math.max(1, Math.min(rawLen || 1, Math.max(1, lineLen - col + 1)));
+  return {
+    line: useKey ? a.keyLine : df.line,
+    col,
+    length,
+    text: df.text,
+    spans: rawLen > length,
+    synthesized: false,
+  };
+}
+
+function headlineFor (err, src) {
+  const p = err.params || {};
+  switch (err.keyword) {
+    case 'additionalProperties':
+      return `unknown property "${p.additionalProperty}"`;
+    case 'unevaluatedProperties':
+      return `unevaluated property "${p.unevaluatedProperty}"`;
+    case 'required':
+      return `missing required property "${p.missingProperty}"`;
+    case 'oneOf': case 'anyOf': {
+      const disc = discriminatorFor(err, src);
+      if (disc) return `no variant matches ${disc.key} ${JSON.stringify(disc.value)}`;
+      return err.detail || err.message || 'no variant matched';
+    }
+    default:
+      return err.detail || err.message || 'validation failed';
+  }
+}
+
+// A discriminator is a property every branch pins with `const`, with distinct
+// values. Anything looser and the code does not guess.
+function discriminatorFor (err, src) {
+  const schema = src.schema;
+  const data = src.data;
+  if (!schema || !data || typeof data !== 'object') return null;
+  const branches = branchesAt(schema, err.schemaPath, err.keyword);
+  if (!Array.isArray(branches) || branches.length < 2) return null;
+
+  const first = branches[0] && branches[0].properties;
+  if (!first) return null;
+  for (const key of Object.keys(first)) {
+    const values = [];
+    let ok = true;
+    for (const b of branches) {
+      const prop = b && b.properties && b.properties[key];
+      if (!prop || prop.const === undefined) { ok = false; break; }
+      if (values.includes(prop.const)) { ok = false; break; }
+      values.push(prop.const);
+    }
+    if (!ok) continue;
+    const actual = data[key];
+    if (actual === undefined) continue;
+    return { key, value: actual };
+  }
+  return null;
+}
+
+// Branch errors arrive raw: keyword, message, instancePath, params. Give each
+// a copy carrying what was expected and what was found, so the note under a
+// composition failure reads as an observation rather than a rule. Copies,
+// never the originals: the array on the error object is a contract.
+function decorateBranches (subs, src) {
+  return subs.map((sub) => {
+    if (!sub || typeof sub !== 'object') return sub;
+    const copy = Object.assign({}, sub);
+    const exp = expectedFor(sub);
+    if (exp !== undefined) copy.expected = exp;
+    if (copy.received === undefined) {
+      const got = valueAt(src.data, sub.instancePath);
+      if (got !== null) copy.received = got;
+    }
+    if (Array.isArray(sub.branchErrors)) copy.branchErrors = decorateBranches(sub.branchErrors, src);
+    return copy;
+  });
+}
+
+// The value a JSON pointer names, as the same short repr enrich() uses for
+// `received`. Null when the data is not in hand or the path does not resolve.
+function valueAt (data, pointer) {
+  if (data === undefined || typeof pointer !== 'string') return null;
+  if (pointer === '') return reprValue(data);
+  let cur = data;
+  for (const seg of pointer.split('/').slice(1)) {
+    if (cur == null || typeof cur !== 'object') return null;
+    cur = cur[seg.replace(/~1/g, '/').replace(/~0/g, '~')];
+  }
+  return cur === undefined ? null : reprValue(cur);
+}
+
+// Walk `#/a/b/anyOf` down to the branch array it names.
+function branchesAt (schema, schemaPath, keyword) {
+  if (typeof schemaPath !== 'string' || !schemaPath.startsWith('#')) {
+    return schema[keyword];
+  }
+  const parts = schemaPath.slice(1).split('/').filter(Boolean).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = schema;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return null;
+    cur = cur[part];
+  }
+  return Array.isArray(cur) ? cur : null;
+}
+
+function singleDiagnostic (e, index, resolved, src) {
+  const pointer = e.instancePath != null ? e.instancePath : (e.path || '');
+  // A composition failure is reported at the container, but the closest
+  // branch already says where inside it the mismatch is. Point there.
+  const closest = e.branchErrors && e.branchErrors.length ? e.branchErrors[0] : null;
+  const anchorErr = closest && closest.instancePath ? closest : e;
+  const frame = frameFor(anchorErr, resolved);
+  // What was found at the caret. A branch error carries no `received`, so
+  // read it off the data when the data is in hand.
+  let found = e.received != null ? e.received : null;
+  if (anchorErr !== e) {
+    found = closest.received != null ? closest.received : valueAt(src.data, closest.instancePath);
+  }
+  const notes = [];
+  if (!frame && resolved.refusal) notes.push(resolved.refusal);
+  if (frame && frame.spans) notes.push('value continues past the end of this line');
+  if (e.docUrl) notes.push('see ' + e.docUrl);
+
+  return {
+    code: e.code,
+    headline: headlineFor(e, src),
+    pointer,
+    dotted: pathToDotted(anchorErr.instancePath != null ? anchorErr.instancePath : pointer),
+    frame,
+    found,
+    help: e.suggestion ? e.suggestion.text : null,
+    notes,
+    branchErrors: e.branchErrors ? decorateBranches(e.branchErrors, src) : null,
+    mergedFrom: [e],
+    rank: typeof e.rank === 'number' ? e.rank : 2,
+    sortPos: frame ? frame.line * 100000 + frame.col : index,
+  };
+}
+
+function mergedDiagnostic (errors, i, j, resolved, src) {
+  const a = errors[i];
+  const b = errors[j];
+  const missing = a.keyword === 'required' ? a : b;
+  const extra = a.keyword === 'required' ? b : a;
+  const missingName = missing.params.missingProperty;
+  const extraName = extra.params.additionalProperty;
+
+  // Anchor on the extra key: that token is the thing the reader edits. The
+  // missing half has no token to point at.
+  const frame = frameFor(extra, resolved);
+  const notes = [];
+  if (!frame && resolved.refusal) notes.push(resolved.refusal);
+  const docUrl = missing.docUrl || extra.docUrl;
+  if (docUrl) notes.push('see ' + docUrl);
+
+  const pointer = missing.instancePath != null ? missing.instancePath : (missing.path || '');
+  return {
+    code: missing.code,
+    headline: `unknown property "${extraName}"`,
+    pointer,
+    dotted: pathToDotted(pointer),
+    frame,
+    found: null,
+    help: `did you mean "${missingName}"?`,
+    notes,
+    branchErrors: null,
+    mergedFrom: [missing, extra],
+    rank: 0,
+    sortPos: frame ? frame.line * 100000 + frame.col : Math.min(i, j),
+  };
+}
+
+module.exports = { toDiagnostics };

package/lib/diagnostic-source.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// Attach to an errors array the material a renderer needs to build frames:
+// the data, the original text when there was one, the schema, and whether
+// validate() changed the data before the verdict.
+//
+// It rides on the array as a non-enumerable symbol property, never on the
+// error objects. JSON.stringify, Object.keys, length and deep equality against
+// a fixture are unchanged. A WeakMap side table was tried and measured: it
+// keyed short-lived arrays, and the ephemeron work pushed the garbage
+// collector to a third of the reject path. A property costs about 80 ns and
+// nothing at collection time.
+const KEY = Symbol.for('ata.diagnosticSource');
+
+// One descriptor, reused. Building a fresh one per call was most of this
+// function's cost in the single-error profile, through the allocation and
+// the collection that followed it.
+const DESCRIPTOR = { value: null, enumerable: false, configurable: true, writable: true };
+
+function setDiagnosticSource (errors, payload) {
+  if (!Array.isArray(errors) || !payload || !Object.isExtensible(errors)) return errors;
+  const prev = errors[KEY];
+  let value = payload;
+  if (prev) {
+    // validateJSON's already-enriched path runs after the validate() wrapper
+    // has recorded the parsed data. Merge, so the text arrives without the
+    // data going missing.
+    value = Object.assign({}, prev);
+    for (const k of Object.keys(payload)) if (payload[k] !== undefined) value[k] = payload[k];
+  }
+  try {
+    DESCRIPTOR.value = value;
+    Object.defineProperty(errors, KEY, DESCRIPTOR);
+    DESCRIPTOR.value = null;
+  } catch {
+    // A validator that throws from its own error path is worse than a
+    // missing frame. The renderer degrades to pointer-only output.
+  }
+  return errors;
+}
+
+function getDiagnosticSource (errors) {
+  return (Array.isArray(errors) && errors[KEY]) || null;
+}
+
+module.exports = { setDiagnosticSource, getDiagnosticSource };