ata-validator 0.14.0 → 0.15.1

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.
@@ -355,6 +363,19 @@ function buildSchemaMap(schemas) {
   return map
 }
 
+// Compile-cache key for a root schema plus its external schemas. Must include
+// the external schema CONTENT, not just their $ids: two validators can share a
+// root schema string and the same $id while pointing that $id at different
+// schemas (separate app instances, test suites, multi-tenant). Keying on $id
+// alone reuses the wrong compiled validator and silently mis-validates.
+function compileCacheKey(schemaStr, schemaMap) {
+  if (!schemaMap || schemaMap.size === 0) return schemaStr
+  const parts = []
+  for (const [id, s] of schemaMap) parts.push(id + '=' + JSON.stringify(s))
+  parts.sort()
+  return schemaStr + '\0' + parts.join('\0')
+}
+
 // Resolve a relative URI ref against a base URI
 function resolveRelativeRef(ref, baseId) {
   if (!baseId || ref.includes('://') || ref.startsWith('#')) return ref
@@ -363,6 +384,66 @@ function resolveRelativeRef(ref, baseId) {
   return baseId.substring(0, lastSlash + 1) + ref
 }
 
+// Resolve a cross-schema $ref to its target schema for preprocessing purposes.
+// Handles whole-schema refs (`shared#`), relative-id matching, and JSON pointer
+// fragments (`shared#/properties/id`). Returns null for local-only refs or when
+// the target cannot be found. Used only to read `type`/`properties` for
+// coercion/defaults/removeAdditional, never for validation.
+function resolveRefForPreprocess(ref, schemaMap) {
+  if (!schemaMap || schemaMap.size === 0 || typeof ref !== 'string') return null
+  const hashIdx = ref.indexOf('#')
+  const baseId = hashIdx >= 0 ? ref.slice(0, hashIdx) : ref
+  const fragment = hashIdx >= 0 ? ref.slice(hashIdx + 1) : ''
+  if (!baseId) return null
+  let base = null
+  if (schemaMap.has(baseId)) base = schemaMap.get(baseId)
+  else if (!ref.includes('://')) {
+    for (const [id, s] of schemaMap) {
+      if (id.endsWith('/' + baseId)) { base = s; break }
+    }
+  }
+  if (!base) return null
+  if (!fragment) return base
+  let target = base
+  for (const part of fragment.split('/')) {
+    if (part === '') continue
+    if (target == null || typeof target !== 'object') return null
+    target = target[part.replace(/~1/g, '/').replace(/~0/g, '~')]
+  }
+  return target == null ? null : target
+}
+
+// Preprocessing (coerce/defaults/removeAdditional) reads `schema.properties` and
+// each property's `type`. When the data shape lives behind a cross-schema $ref
+// (a whole-schema ref like Fastify's `params: { $ref: 'shared#' }`, or a
+// property ref like `{ id: { $ref: 'shared#/properties/id' } }`), follow the
+// ref so the preprocessor can see the referenced shape. Returns the schema with
+// such refs resolved, cloning only when a substitution is made.
+function resolveSchemaForPreprocess(schema, schemaMap) {
+  if (!schema || typeof schema !== 'object' || !schemaMap || schemaMap.size === 0) return schema
+  let s = schema
+  // Whole-schema ref (only when it has no own properties, to avoid dropping
+  // sibling keywords on schemas that mix $ref with properties).
+  if (s.$ref && !s.properties) {
+    const t = resolveRefForPreprocess(s.$ref, schemaMap)
+    if (t && typeof t === 'object') s = t
+  }
+  if (!s.properties) return s
+  // Property-level refs: substitute the resolved target so coercion sees `type`.
+  let cloned = null
+  for (const key of Object.keys(s.properties)) {
+    const p = s.properties[key]
+    if (p && typeof p === 'object' && p.$ref && !p.type) {
+      const t = resolveRefForPreprocess(p.$ref, schemaMap)
+      if (t && typeof t === 'object') {
+        if (!cloned) { cloned = Object.assign({}, s); cloned.properties = Object.assign({}, s.properties) }
+        cloned.properties[key] = t
+      }
+    }
+  }
+  return cloned || s
+}
+
 class Validator {
   constructor(schema, opts) {
     const options = opts || {};
@@ -402,6 +483,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();
@@ -497,9 +604,7 @@ class Validator {
 
     // Check cache first -- reuse compiled functions for same schema
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
-    const mapKey = this._schemaMap.size > 0
-      ? this._schemaStr + '\0' + [...this._schemaMap.keys()].sort().join('\0')
-      : this._schemaStr;
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
     // Custom formats are JS functions: bypass the compile cache since they can
     // differ between validators that share the same schema string.
     const cached = this._userFormats ? null : _compileCache.get(mapKey);
@@ -525,13 +630,17 @@ class Validator {
     }
     this._jsFn = jsFn;
 
-    // Data mutators -- try codegen first (12x faster), fallback to closure arrays
-    let preprocess = buildPreprocessCodegen(schemaObj, options);
+    // Data mutators -- try codegen first (12x faster), fallback to closure arrays.
+    // Follow cross-refs so coercion/defaults/removeAdditional see the referenced
+    // shape (e.g. Fastify `params: { $ref: 'shared#' }` or property refs like
+    // `{ id: { $ref: 'shared#/properties/id' } }`).
+    const preprocessSchema = resolveSchemaForPreprocess(schemaObj, this._schemaMap);
+    let preprocess = buildPreprocessCodegen(preprocessSchema, options);
     if (!preprocess) {
-      const applyDefaults = buildDefaultsApplier(schemaObj);
-      const applyCoerce = options.coerceTypes ? buildCoercer(schemaObj) : null;
+      const applyDefaults = buildDefaultsApplier(preprocessSchema);
+      const applyCoerce = options.coerceTypes ? buildCoercer(preprocessSchema) : null;
       const applyRemove = options.removeAdditional
-        ? buildRemover(schemaObj)
+        ? buildRemover(preprocessSchema)
         : null;
       const mutators = [applyRemove, applyCoerce, applyDefaults].filter(Boolean);
       preprocess =
@@ -626,8 +735,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 +962,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);
@@ -891,9 +1082,7 @@ class Validator {
     if (typeof process !== 'undefined' && process.env && process.env.ATA_FORCE_NAPI) return;
     if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
-    const mapKey = this._schemaMap.size > 0
-      ? this._schemaStr + '\0' + [...this._schemaMap.keys()].sort().join('\0')
-      : this._schemaStr;
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
     // Custom formats are JS functions: skip the shared cache so different
     // validators with the same schema string but different formats don't collide.
     const cached = this._userFormats ? null : _compileCache.get(mapKey);
@@ -965,12 +1154,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 +1173,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 +1221,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 +1602,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 +1651,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 };