ata-validator 0.13.4 → 0.15.0

package/index.js

@@ -272,7 +272,15 @@ const _identityCache = new WeakMap();
 
 const SIMDJSON_PADDING = 64;
 const VALID_RESULT = Object.freeze({ valid: true, errors: Object.freeze([]) });
-const ABORT_EARLY_RESULT = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ message: 'validation failed' })]) });
+const ABORT_EARLY_RESULT = Object.freeze({
+  valid: false,
+  errors: Object.freeze([Object.freeze({
+    code: 'ATA9000',
+    message: 'validation failed',
+    keyword: '__abort_early__',
+    path: '',
+  })]),
+});
 
 // Embedded verbatim in standalone modules so the output file has no runtime
 // dependency on ata-validator. ASCII fast-path plus surrogate-aware slow path.
@@ -402,6 +410,32 @@ class Validator {
     // produced the error). Matches ajv's `verbose: true` behavior.
     this._verbose = !!options.verbose;
 
+    // richErrors: default true. Only the literal `false` opts back into the
+    // v0.14 error shape (no code/expected/received/docUrl, no aliases).
+    this._richErrors = options && options.richErrors === false ? false : true;
+
+    // Optional schema source descriptor. When supplied, the renderer pipeline
+    // can attach a `schemaSource` frame to enriched errors.
+    this._source = options && options.source && typeof options.source === 'object'
+      ? { path: String(options.source.path || ''), content: String(options.source.content || '') }
+      : null;
+
+    // Build a JSON pointer -> position map for the schema text once at
+    // construction so each runtime error can resolve `schemaSource` without
+    // re-scanning the source on every validate() call.
+    if (this._source) {
+      const { buildPositionMap } = require('./lib/source-positions');
+      this._schemaPositions = buildPositionMap(this._source.content);
+    } else {
+      this._schemaPositions = null;
+    }
+
+    // Per-validate data position cache. Populated by validateJSON before
+    // dispatching to inner validate(); consulted by the rich-error wrap
+    // to attach dataFrame entries to each enriched error.
+    this._posCache = require('./lib/data-position-cache').createCache();
+    this._lastRawInput = null;
+
     // Lazy stubs: trigger compilation on first call, then re-dispatch
     this.validate = (data) => {
       this._ensureCompiled();
@@ -626,8 +660,10 @@ class Validator {
       }
 
       if (options.abortEarly && jsFn && !hasDynRef) {
-        // Abort-early fast path: skip detailed error collection on failure.
-        // Returns a shared frozen result, no per-call allocation, no errFn work.
+        // abortEarly: do NOT enrich. Skip position lookups, suggestions, source maps.
+        // This is the perf-critical path for edge gateways. The richErrors wrap
+        // below recognises the ATA9000 stub keyword and passes the frozen result
+        // through unchanged, so a single shared object is returned per failure.
         const _fn = jsFn;
         this.validate = preprocess
           ? (data) => { preprocess(data); return _fn(data) ? VALID_RESULT : ABORT_EARLY_RESULT; }
@@ -851,6 +887,86 @@ class Validator {
       }
     }
 
+    // richErrors enrichment: layered on top of whichever validate path was
+    // bound above. Verbose's parentSchema flows through because enrich()
+    // copies it. Opt-out (`richErrors: false`) leaves the raw v0.14 shape.
+    if (this._richErrors && this.validate) {
+      const inner = this.validate;
+      const enrich = require('./lib/enrich-error').enrich;
+      this.validate = (data) => {
+        const result = inner(data);
+        if (result && !result.valid && result.errors && result.errors.length) {
+          // abortEarly returns the shared ATA9000 stub; preserve it as-is so the
+          // perf fast path stays allocation-free and the documented code stays stable.
+          if (result === ABORT_EARLY_RESULT) return result;
+          const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
+          const enriched = result.errors.map((e) => enrich(e, {
+            data,
+            positions,
+            schemaPositions: this._schemaPositions,
+            schemaFile: this._source ? this._source.path : undefined,
+          }));
+          if (positions) this._posCache.reset();
+          return { valid: false, errors: enriched };
+        }
+        return result;
+      };
+
+      // validateJSON also enriches: set _lastRawInput so the position cache
+      // can lazily build a map for dataFrame attachment. Only validateJSON
+      // wires this — validate(data) takes a pre-parsed object, by design.
+      if (this.validateJSON) {
+        const innerJson = this.validateJSON;
+        this.validateJSON = (jsonStr) => {
+          this._lastRawInput = jsonStr;
+          let result;
+          try {
+            result = innerJson(jsonStr);
+          } finally {
+            // Don't clear here; the enrich step below needs the cache. We
+            // clear after enrich, or in the early-return path.
+          }
+          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`.
+            const first = result.errors[0];
+            if (!first || !first.code) {
+              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 (positions) this._posCache.reset();
+              this._lastRawInput = null;
+              return { valid: false, errors: enriched };
+            }
+            // Already-enriched path: still attach dataFrame if missing.
+            const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
+            if (positions) {
+              for (const e of result.errors) {
+                if (e && !e.dataFrame) {
+                  const path = e.path != null ? e.path : (e.instancePath || '');
+                  const p = positions[path];
+                  if (p) e.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
+                }
+              }
+              this._posCache.reset();
+            }
+          }
+          this._lastRawInput = null;
+          return result;
+        };
+      }
+    }
+
     // Save to identity cache for ultra-fast reuse with same schema object
     if (this._schemaObj && typeof this._schemaObj === 'object') {
       _identityCache.set(this._schemaObj, this);
@@ -965,12 +1081,18 @@ module.exports = { boolFn, hybridFactory, errFn };
     if (!jsFn || !jsFn._source) return null;
     const format = (opts && opts.format) || 'esm';
     const abortEarly = !!(opts && opts.abortEarly);
+    const source = !!(opts && opts.source);
+    const sourceMap = opts && opts.sourceMap ? opts.sourceMap : null;
+    const schemaFile = opts && opts.schemaFile ? opts.schemaFile : null;
     const src = jsFn._source;
 
     let errCore = '';
     if (!abortEarly) {
       const jsErrFn = compileToJSCodegenWithErrors(
         typeof this._schemaObj === 'object' ? this._schemaObj : {},
+        null,
+        undefined,
+        (source && sourceMap && schemaFile) ? { sourceMap, schemaFile } : null,
       );
       const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
       if (errSrc) {
@@ -978,6 +1100,16 @@ module.exports = { boolFn, hybridFactory, errFn };
       }
     }
 
+    // Schema-source frames are baked as literals inside each emitted error so
+    // consumers don't need a runtime lookup. We still expose the schema file
+    // as a sentinel constant when --source is on — handy for introspection
+    // and visible in source graphs. With --no-source, the constant is omitted
+    // 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`
+      : '';
+
     // Serialize closure vars referenced in _fn body: regex, sub-validators, sets.
     let closureDecls = '';
     if (jsFn._closures && jsFn._closures.length > 0) {
@@ -1016,8 +1148,16 @@ module.exports = { boolFn, hybridFactory, errFn };
 // Schema is embedded; runtime has zero dependency on ata-validator.
 'use strict';
 ${_CP_LEN_SOURCE}
-const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
-const ABORT = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ message: 'validation failed' })]) });
+${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+const ABORT = Object.freeze({
+  valid: false,
+  errors: Object.freeze([Object.freeze({
+    code: 'ATA9000',
+    message: 'validation failed',
+    keyword: '__abort_early__',
+    path: '',
+  })]),
+});
 ${closureDecls}const _fn = function(d) {
   ${src}
 };
@@ -1389,6 +1529,45 @@ function compile(schema, opts) {
 }
 
 const { toTypeScript } = require("./lib/ts-gen");
+const { renderPretty } = require("./lib/render-pretty");
+const { renderCompact } = require("./lib/render-compact");
+const { renderJSON } = require("./lib/render-json");
+const { suggestFor } = require("./lib/suggestions");
+const { reprValue } = require("./lib/enrich-error");
+
+// Walk a JSON pointer (RFC 6901 escapes) into a data tree. Mirrors the helper
+// inside lib/suggestions.js — kept local to avoid exporting an internal.
+function _walkPointer (root, pointer) {
+  if (!pointer) return root;
+  const parts = pointer.replace(/^\//, '').split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = root;
+  for (const p of parts) { if (cur == null) return undefined; cur = cur[p]; }
+  return cur;
+}
+
+// Post-hoc suggestion enrichment for AOT-compiled validators. The standalone
+// modules do not embed the suggestion engine (Levenshtein + format hints would
+// 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.
+function attachSuggestions (errors, data) {
+  if (!errors) return errors;
+  for (const e of errors) {
+    if (!e || e.suggestion) continue;
+    let received = e.received;
+    if (received === undefined && data !== undefined) {
+      const ptr = e.instancePath != null ? e.instancePath : (e.path || '');
+      const raw = _walkPointer(data, ptr);
+      if (raw !== undefined || ptr === '') received = reprValue(raw);
+    }
+    const probe = received !== undefined && e.received === undefined
+      ? Object.assign({}, e, { received })
+      : e;
+    const s = suggestFor(probe, data);
+    if (s) e.suggestion = s;
+  }
+  return errors;
+}
 
 module.exports = {
   Validator,
@@ -1399,4 +1578,8 @@ module.exports = {
   SIMDJSON_PADDING,
   parseJSON,
   toTypeScript,
+  renderPretty,
+  renderCompact,
+  renderJSON,
+  attachSuggestions,
 };

package/index.mjs

@@ -1,3 +1,3 @@
 import mod from './index.js';
-export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING } = mod;
+export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, renderPretty, renderCompact, renderJSON } = mod;
 export default mod;

package/lib/aot-build.js

@@ -5,6 +5,13 @@ const fs = require('fs');
 const path = require('path');
 const zlib = require('zlib');
 const { Validator } = require('..');
+const { buildPositionMap } = require('./source-positions');
+
+function resolveSourceDefault (opts) {
+  if (opts.source === true) return true;
+  if (opts.source === false) return false;
+  return process.env.NODE_ENV !== 'production';
+}
 
 async function expandGlobs(globs) {
   const out = [];
@@ -120,7 +127,24 @@ async function build(opts) {
       }
       const schema = parseSchemaFile(input);
       const v = new Validator(schema);
-      const src = v.toStandaloneModule({ format, abortEarly: !!opts.abortEarly });
+      const source = resolveSourceDefault(opts);
+      let sourceMap = null;
+      if (source) {
+        // Only attempt position map for JSON (the scanner is JSON-only).
+        const ext = path.extname(input).toLowerCase();
+        if (ext === '.json') {
+          try { sourceMap = buildPositionMap(raw.toString('utf8')); }
+          catch { sourceMap = null; }
+        }
+      }
+      const schemaFile = path.relative(process.cwd(), input) || input;
+      const src = v.toStandaloneModule({
+        format,
+        abortEarly: !!opts.abortEarly,
+        source,
+        sourceMap,
+        schemaFile,
+      });
       if (!src) {
         const reason = 'schema is not AOT-compatible (toStandaloneModule returned null)';
         if (opts.strict) failed.push({ input, error: reason });

package/lib/branch-collapse.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const SEVERITY = {
+  type: 10,
+  const: 8,
+  enum: 8,
+  required: 5,
+  format: 3,
+  minLength: 3,
+  maxLength: 3,
+  minimum: 3,
+  maximum: 3,
+  pattern: 3,
+  additionalProperties: 2,
+  unevaluatedProperties: 2,
+  unevaluatedItems: 2,
+};
+const DEFAULT_SEVERITY = 4;
+
+function scoreBranch (errors) {
+  if (!errors || errors.length === 0) return 0;
+  let sum = 0;
+  for (const e of errors) sum += SEVERITY[e.keyword] || DEFAULT_SEVERITY;
+  return errors.length * 100 + sum; // primary: count, secondary: severity
+}
+
+/**
+ * Given an array of branch result objects ({ valid, errors }) for a oneOf
+ * or anyOf, pick the best branch and emit a single user-facing error.
+ *
+ * @param keyword 'oneOf' | 'anyOf'
+ * @param branchResults Array<{ valid, errors, title? }>
+ * @param parentPath JSON pointer to the data location
+ * @param parentSchemaPath JSON pointer to the keyword in the schema
+ * @returns A ValidationError-shaped object, or null if branch passed (caller treats as success).
+ */
+function collapseBranches ({ keyword, branchResults, parentPath, parentSchemaPath }) {
+  const passing = branchResults.filter(b => b.valid);
+  if (keyword === 'oneOf') {
+    if (passing.length === 1) return null;
+    if (passing.length > 1) {
+      return {
+        code: 'ATA4002', keyword: 'oneOf', path: parentPath || '',
+        message: `value matched ${passing.length} of ${branchResults.length} oneOf variants, expected exactly one`,
+        schemaPath: parentSchemaPath,
+        params: { matched: passing.length, total: branchResults.length },
+      };
+    }
+    // 0 matched, find best
+    return buildBranchError('ATA4001', 'oneOf', branchResults, parentPath, parentSchemaPath);
+  }
+  // anyOf
+  if (passing.length >= 1) return null;
+  return buildBranchError('ATA4003', 'anyOf', branchResults, parentPath, parentSchemaPath);
+}
+
+function buildBranchError (code, keyword, branchResults, parentPath, parentSchemaPath) {
+  let bestIdx = 0;
+  let bestScore = Infinity;
+  for (let i = 0; i < branchResults.length; i++) {
+    const s = scoreBranch(branchResults[i].errors);
+    if (s < bestScore) { bestScore = s; bestIdx = i; }
+  }
+  const best = branchResults[bestIdx];
+  const variantName = best.title || `variant ${bestIdx + 1}`;
+  return {
+    code, keyword, path: parentPath || '',
+    message: `value matched 0 of ${branchResults.length} ${keyword} variants`,
+    schemaPath: parentSchemaPath,
+    params: { variants: branchResults.length, closest: bestIdx, closestName: variantName },
+    branchErrors: best.errors, // surfaced in pretty render
+  };
+}
+
+module.exports = { collapseBranches, scoreBranch, SEVERITY };

package/lib/data-position-cache.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const { buildDataPositionMap } = require('./data-positions');
+
+/**
+ * Memoize the position map for the duration of a single validate() call.
+ * Caller passes the original buffer/string. Identity-keyed: same reference
+ * == same map. No global state, caller holds the cache instance.
+ */
+
+function createCache () {
+  const wm = new WeakMap();
+  const sm = new Map(); // strings can't go in WeakMap; clear after each validate
+  let lastInput = null;
+  return {
+    get (input) {
+      if (input == null) return null;
+      if (typeof input === 'string') {
+        if (sm.has(input)) return sm.get(input);
+        try {
+          const m = buildDataPositionMap(input);
+          sm.set(input, m);
+          return m;
+        } catch { return null; }
+      }
+      if (Buffer.isBuffer(input)) {
+        if (wm.has(input)) return wm.get(input);
+        try {
+          const m = buildDataPositionMap(input);
+          wm.set(input, m);
+          return m;
+        } catch { return null; }
+      }
+      return null;
+    },
+    reset () {
+      sm.clear();
+      lastInput = null;
+    },
+  };
+}
+
+module.exports = { createCache };

package/lib/data-positions.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Build pointer → { byteOffset, length, line, col, text } from a JSON
+ * input buffer. Called only when validation fails AND richErrors is on
+ * AND abortEarly is off. Zero cost on the valid path.
+ */
+
+const { escapePtr } = require('./source-positions');
+
+function buildDataPositionMap (input) {
+  const text = Buffer.isBuffer(input) ? input.toString('utf8') : String(input);
+  const map = Object.create(null);
+  const lines = text.split('\n');
+  const lineStart = new Array(lines.length + 1);
+  lineStart[0] = 0;
+  for (let i = 0; i < lines.length; i++) lineStart[i + 1] = lineStart[i] + lines[i].length + 1;
+
+  function offsetToLineCol (off) {
+    let lo = 0, hi = lineStart.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (lineStart[mid] <= off) lo = mid; else hi = mid - 1;
+    }
+    return { line: lo + 1, col: off - lineStart[lo] + 1, text: lines[lo] || '' };
+  }
+
+  let i = 0;
+  const n = text.length;
+
+  function skipWs () {
+    while (i < n) {
+      const ch = text.charCodeAt(i);
+      if (ch === 0x20 || ch === 0x09 || ch === 0x0a || ch === 0x0d) i++; else break;
+    }
+  }
+
+  function readString () {
+    const start = i;
+    i++;
+    while (i < n) {
+      const ch = text.charCodeAt(i);
+      if (ch === 0x5c) { i += 2; continue; }
+      if (ch === 0x22) { i++; return JSON.parse(text.slice(start, i)); }
+      i++;
+    }
+    throw new Error('unterminated string at offset ' + start);
+  }
+
+  function pointerOf (path) {
+    if (path.length === 0) return '';
+    return '/' + path.map(escapePtr).join('/');
+  }
+
+  function walk (path) {
+    skipWs();
+    if (i >= n) return;
+    const start = i;
+    const pos = offsetToLineCol(start);
+
+    const ch = text.charCodeAt(i);
+    if (ch === 0x7b) {
+      i++;
+      while (true) {
+        skipWs();
+        if (text.charCodeAt(i) === 0x7d) { i++; break; }
+        if (text.charCodeAt(i) === 0x2c) { i++; continue; }
+        skipWs();
+        const key = readString();
+        skipWs();
+        if (text.charCodeAt(i) !== 0x3a) throw new Error('expected ":" at offset ' + i);
+        i++;
+        walk(path.concat([key]));
+      }
+    } else if (ch === 0x5b) {
+      i++;
+      let idx = 0;
+      while (true) {
+        skipWs();
+        if (text.charCodeAt(i) === 0x5d) { i++; break; }
+        if (text.charCodeAt(i) === 0x2c) { i++; continue; }
+        walk(path.concat([String(idx)]));
+        idx++;
+      }
+    } else if (ch === 0x22) {
+      readString();
+    } else {
+      while (i < n) {
+        const c = text.charCodeAt(i);
+        if (c === 0x2c || c === 0x7d || c === 0x5d || c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) break;
+        i++;
+      }
+    }
+
+    const length = i - start;
+    map[pointerOf(path)] = { byteOffset: start, length, line: pos.line, col: pos.col, text: pos.text };
+  }
+
+  if (text.charCodeAt(0) === 0xfeff) i = 1;
+  walk([]);
+  return map;
+}
+
+module.exports = { buildDataPositionMap };

package/lib/enrich-error.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const { CODES, codeFor } = require('./error-codes');
+const { suggestFor } = require('./suggestions');
+
+const DOC_BASE = 'https://ata-validator.com/e/';
+
+function reprValue (v) {
+  if (v === undefined) return 'undefined';
+  if (v === null) return 'null';
+  const t = typeof v;
+  if (t === 'string') {
+    const s = JSON.stringify(v);
+    return s.length > 60 ? s.slice(0, 57) + '..."' : s;
+  }
+  if (t === 'number' || t === 'boolean') return String(v);
+  if (Array.isArray(v)) return `[array, ${v.length} items]`;
+  if (t === 'object') {
+    try {
+      const s = JSON.stringify(v);
+      if (s.length <= 60) return s;
+      return `[object, ~${(s.length / 1024).toFixed(1)}KB]`;
+    } catch {
+      return '[object, unserializable]';
+    }
+  }
+  return `[${t}]`;
+}
+
+function expectedFor (err) {
+  switch (err.keyword) {
+    case 'type': return err.params && err.params.type ? String(err.params.type) : undefined;
+    case 'minLength': return err.params && err.params.limit != null ? `string with ≥${err.params.limit} chars` : undefined;
+    case 'maxLength': return err.params && err.params.limit != null ? `string with ≤${err.params.limit} chars` : undefined;
+    case 'minimum': return err.params && err.params.limit != null ? `≥${err.params.limit}` : undefined;
+    case 'maximum': return err.params && err.params.limit != null ? `≤${err.params.limit}` : undefined;
+    case 'format': return err.params && err.params.format ? `format '${err.params.format}'` : undefined;
+    case 'enum': return err.params && err.params.allowedValues
+      ? `one of [${err.params.allowedValues.map(reprValue).join(', ')}]`
+      : undefined;
+    case 'const': return err.params && 'allowedValue' in err.params ? reprValue(err.params.allowedValue) : undefined;
+    case 'required': return err.params && err.params.missingProperty ? `property '${err.params.missingProperty}'` : undefined;
+    default: return undefined;
+  }
+}
+
+function pickReceived (err, data) {
+  if (!data && data !== 0 && data !== false) return undefined;
+  // Walk JSON pointer to extract the actual offending value
+  const p = err.instancePath || err.path || '';
+  if (!p) return reprValue(data);
+  const parts = p.replace(/^\//, '').split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = data;
+  for (const part of parts) {
+    if (cur == null) return undefined;
+    cur = cur[part];
+  }
+  return reprValue(cur);
+}
+
+/**
+ * Enrich a raw codegen error with code/path/expected/received/docUrl.
+ * Pure: returns a new object. Source frames and suggestions are added by
+ * other helpers later in the pipeline.
+ */
+function enrich (rawErr, opts) {
+  const data = opts && opts.data;
+  const positions = opts && opts.positions;
+  const keyword = rawErr.keyword;
+  const format = rawErr.params && rawErr.params.format;
+  // 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'`.
+  const code = rawErr.code || codeFor(keyword, format) || 'ATA9001';
+  const meta = CODES[code];
+  const path = rawErr.instancePath != null ? rawErr.instancePath : (rawErr.path || '');
+
+  const out = {
+    code,
+    message: rawErr.message || (meta && meta.headline) || 'validation failed',
+    keyword,
+    path,
+    expected: expectedFor(rawErr),
+    received: data !== undefined ? pickReceived(rawErr, data) : undefined,
+    schemaPath: rawErr.schemaPath,
+    docUrl: DOC_BASE + code,
+    // Back-compat aliases (additive, present in both rich and legacy paths)
+    instancePath: path,
+    dataPath: path,
+    params: rawErr.params,
+    parentSchema: rawErr.parentSchema,
+  };
+
+  // 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;
+
+  if (positions && positions[path]) {
+    const p = positions[path];
+    out.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
+  }
+
+  // Attach schema source frame when the validator was constructed with a
+  // `source` option. schemaPath looks like "#/properties/email/format" — strip
+  // the leading "#" before lookup. Fall back to the `#key` variant which the
+  // position scanner stores for the keyword name itself.
+  if (opts && opts.schemaPositions && rawErr.schemaPath) {
+    const sp = rawErr.schemaPath;
+    const ptr = sp.startsWith('#') ? sp.slice(1) : sp;
+    const hit = opts.schemaPositions[ptr] || opts.schemaPositions[ptr + '#key'];
+    if (hit) {
+      out.schemaSource = { file: opts.schemaFile, line: hit.line, col: hit.col, text: hit.text };
+    }
+  }
+
+  // Suggestion attachment runs last so it can read `received`, `params`, and
+  // `keyword` from the enriched shape. `data` is the full input object so the
+  // required-typo source can scan sibling keys.
+  const sugg = suggestFor(out, opts && opts.data);
+  if (sugg) out.suggestion = sugg;
+
+  return out;
+}
+
+module.exports = { enrich, reprValue, expectedFor };