ata-validator 0.14.0 → 0.15.0

package/lib/error-codes.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// Single source of truth for ATA error codes.
+// STABILITY: once a code is published, its keyword and category never change.
+// Removal is forbidden; mark deprecated instead. Adding requires updating
+// tests/error-codes.lock.json in the same PR.
+
+const CODES = Object.freeze({
+  // ATA1xxx — type / shape
+  ATA1001: { keyword: 'type', category: 'type', headline: 'value has wrong type' },
+  ATA1002: { keyword: 'type', category: 'type', headline: 'value is not an object' },
+
+  // ATA2xxx — constraint
+  ATA2001: { keyword: 'minLength', category: 'constraint', headline: 'string shorter than minLength' },
+  ATA2002: { keyword: 'maxLength', category: 'constraint', headline: 'string longer than maxLength' },
+  ATA2003: { keyword: 'minimum', category: 'constraint', headline: 'number below minimum' },
+  ATA2004: { keyword: 'maximum', category: 'constraint', headline: 'number above maximum' },
+  ATA2005: { keyword: 'exclusiveMinimum', category: 'constraint', headline: 'number not above exclusiveMinimum' },
+  ATA2006: { keyword: 'exclusiveMaximum', category: 'constraint', headline: 'number not below exclusiveMaximum' },
+  ATA2007: { keyword: 'multipleOf', category: 'constraint', headline: 'number not a multiple of expected divisor' },
+  ATA2008: { keyword: 'minItems', category: 'constraint', headline: 'array shorter than minItems' },
+  ATA2009: { keyword: 'maxItems', category: 'constraint', headline: 'array longer than maxItems' },
+  ATA2010: { keyword: 'minProperties', category: 'constraint', headline: 'object has fewer than minProperties' },
+  ATA2011: { keyword: 'maxProperties', category: 'constraint', headline: 'object has more than maxProperties' },
+  ATA2012: { keyword: 'uniqueItems', category: 'constraint', headline: 'array has duplicate items' },
+  ATA2013: { keyword: 'pattern', category: 'constraint', headline: 'string does not match pattern' },
+
+  // ATA3xxx — format
+  ATA3001: { keyword: 'format', format: 'email', category: 'format', headline: 'value does not match format "email"' },
+  ATA3002: { keyword: 'format', format: 'date', category: 'format', headline: 'value does not match format "date"' },
+  ATA3003: { keyword: 'format', format: 'date-time', category: 'format', headline: 'value does not match format "date-time"' },
+  ATA3004: { keyword: 'format', format: 'time', category: 'format', headline: 'value does not match format "time"' },
+  ATA3005: { keyword: 'format', format: 'uri', category: 'format', headline: 'value does not match format "uri"' },
+  ATA3006: { keyword: 'format', format: 'uri-reference', category: 'format', headline: 'value does not match format "uri-reference"' },
+  ATA3007: { keyword: 'format', format: 'ipv4', category: 'format', headline: 'value does not match format "ipv4"' },
+  ATA3008: { keyword: 'format', format: 'ipv6', category: 'format', headline: 'value does not match format "ipv6"' },
+  ATA3009: { keyword: 'format', format: 'uuid', category: 'format', headline: 'value does not match format "uuid"' },
+  ATA3010: { keyword: 'format', format: 'hostname', category: 'format', headline: 'value does not match format "hostname"' },
+  ATA3099: { keyword: 'format', category: 'format', headline: 'value does not match user-defined format' },
+
+  // ATA4xxx — composition
+  ATA4001: { keyword: 'oneOf', category: 'composition', headline: 'value matched 0 of N oneOf variants' },
+  ATA4002: { keyword: 'oneOf', category: 'composition', headline: 'value matched more than one oneOf variant' },
+  ATA4003: { keyword: 'anyOf', category: 'composition', headline: 'value matched none of the anyOf variants' },
+  ATA4004: { keyword: 'allOf', category: 'composition', headline: 'value failed one or more allOf branches' },
+  ATA4005: { keyword: 'not', category: 'composition', headline: 'value matched a forbidden schema' },
+  ATA4006: { keyword: 'if', category: 'composition', headline: 'value violated then/else branch' },
+
+  // ATA5xxx — refs
+  ATA5001: { keyword: '$ref', category: 'ref', headline: '$ref could not be resolved' },
+  ATA5002: { keyword: '$ref', category: 'ref', headline: 'recursive $ref cycle detected at validate time' },
+
+  // ATA6xxx — enum/const
+  ATA6001: { keyword: 'enum', category: 'enum', headline: 'value is not one of the allowed enum values' },
+  ATA6002: { keyword: 'const', category: 'enum', headline: 'value does not equal const' },
+
+  // ATA7xxx — required / additional / unevaluated
+  ATA7001: { keyword: 'required', category: 'shape', headline: 'object missing required property' },
+  ATA7002: { keyword: 'additionalProperties', category: 'shape', headline: 'object has property not allowed by schema' },
+  ATA7003: { keyword: 'unevaluatedProperties', category: 'shape', headline: 'object has unevaluated property' },
+  ATA7004: { keyword: 'unevaluatedItems', category: 'shape', headline: 'array has unevaluated items' },
+  ATA7005: { keyword: 'dependentRequired', category: 'shape', headline: 'dependentRequired property missing' },
+  ATA7006: { keyword: 'propertyNames', category: 'shape', headline: 'property name violates schema' },
+  ATA7007: { keyword: 'contains', category: 'shape', headline: 'array does not contain a matching item' },
+
+  // ATA9xxx — system
+  ATA9000: { keyword: '__abort_early__', category: 'system', headline: 'validation failed (abortEarly)' },
+  ATA9001: { keyword: '__parse__', category: 'system', headline: 'input is not valid JSON' },
+  ATA9002: { keyword: '__compile__', category: 'system', headline: 'schema failed to compile' },
+});
+
+function get (code) {
+  return CODES[code];
+}
+
+function all () {
+  return Object.keys(CODES).sort();
+}
+
+// Map a (keyword, optional format) tuple back to a code. Used by the codegen
+// integration to attach codes to existing error sites without rewriting them all.
+function codeFor (keyword, format) {
+  if (keyword === 'format' && format) {
+    for (const c of all()) {
+      const meta = CODES[c];
+      if (meta.keyword === 'format' && meta.format === format) return c;
+    }
+    return 'ATA3099';
+  }
+  for (const c of all()) {
+    if (CODES[c].keyword === keyword) return c;
+  }
+  return null;
+}
+
+module.exports = { CODES, get, all, codeFor };

package/lib/js-compiler.js

@@ -1,9 +1,43 @@
 'use strict'
 
+const { codeFor } = require('./error-codes')
+
 // Compile a JSON Schema into a pure JS validator function.
 // Closure-based validator — no new Function() or eval().
 // Returns null if the schema is too complex for JS compilation.
 
+const DOC_BASE = 'https://ata-validator.com/e/'
+
+// Build the literal fragments injected into an emitted _e.push({...}) call.
+// Returns { codeStr, docUrl, frame } where `frame` is a JS source fragment
+// like ",schemaSource:Object.freeze({...})" or "" if no source map hit.
+// The fragment always starts with a leading comma when non-empty so callers
+// can splice it inside an existing object literal.
+function buildErrorLiteral (opts) {
+  const { keyword, format, schemaPath, sourceMap } = opts
+  let code = (keyword === 'format' && format) ? codeFor('format', format) : codeFor(keyword)
+  if (!code) code = 'ATA9001'
+  const docUrl = DOC_BASE + code
+  let frame = ''
+  if (sourceMap && sourceMap.file && sourceMap.map) {
+    const ptr = schemaPath && schemaPath.charAt(0) === '#' ? schemaPath.slice(1) : (schemaPath || '')
+    let hit = sourceMap.map[ptr + '#key']
+    if (!hit) hit = sourceMap.map[ptr]
+    if (hit) {
+      // Support both {line,col,text} (raw output of buildPositionMap) and
+      // [line,col,text] (compact form passed by callers that pre-flattened).
+      const line = Array.isArray(hit) ? hit[0] : hit.line
+      const col = Array.isArray(hit) ? hit[1] : hit.col
+      const text = Array.isArray(hit) ? hit[2] : hit.text
+      frame = ',schemaSource:Object.freeze({file:' + JSON.stringify(sourceMap.file) +
+        ',line:' + line +
+        ',col:' + col +
+        ',text:' + JSON.stringify(text) + '})'
+    }
+  }
+  return { codeStr: code, docUrl, frame }
+}
+
 // Count Unicode code points, not UTF-16 code units (surrogate pairs).
 // JSON Schema: minLength/maxLength count characters per RFC 8259.
 // Fast path: if no surrogate pairs exist, .length is correct (covers >99% of real data).
@@ -2471,7 +2505,7 @@ function genCharCodeSwitch(keys, v) {
 // --- Error-collecting codegen: same checks, but pushes errors instead of returning false ---
 // Returns a function: (data, allErrors) => { valid, errors }
 // Valid path is still fast — only error path does extra work.
-function compileToJSCodegenWithErrors(schema, schemaMap, userFormats) {
+function compileToJSCodegenWithErrors(schema, schemaMap, userFormats, sourceOpts) {
   // Bail on unevaluated keywords — error codegen doesn't support them yet
   if (typeof schema === 'object' && schema !== null) {
     const s = JSON.stringify(schema)
@@ -2532,10 +2566,20 @@ function compileToJSCodegenWithErrors(schema, schemaMap, userFormats) {
     }
   }
 
-  const ctx = { varCounter: 0, helperCode: [], rootDefs: eRootDefs, refStack: new Set(), schemaMap: schemaMap || null, anchors: eAnchors, rootSchema: schema, userFormats: userFormats || null }
+  const ctx = { varCounter: 0, helperCode: [], rootDefs: eRootDefs, refStack: new Set(), schemaMap: schemaMap || null, anchors: eAnchors, rootSchema: schema, userFormats: userFormats || null,
+                sourceMap: (sourceOpts && sourceOpts.sourceMap && sourceOpts.schemaFile)
+                  ? { file: sourceOpts.schemaFile, map: sourceOpts.sourceMap }
+                  : null }
   ctx.helperCode.push('const _cpLen=s=>{let n=0;for(const _ of s)n++;return n}')
   const lines = []
   genCodeE(schema, 'd', '', lines, ctx, '#')
+  // Inline branch-collapse helper only when the schema actually used a
+  // oneOf/anyOf branch path (tracked via ctx.usesBranchCollapse). Keeps the
+  // AOT output small for schemas that don't compose. Standalone modules can't
+  // require('./branch-collapse'), so the helper body is embedded verbatim.
+  if (ctx.usesBranchCollapse) {
+    ctx.helperCode.push("const __ATA_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};function __ataScore(errs){if(!errs||!errs.length)return 0;let s=0;for(const e of errs)s+=__ATA_SEVERITY[e.keyword]||4;return errs.length*100+s}function __ataCollapse(kw,br,pp,sp){const pass=br.filter(b=>b.valid);if(kw==='oneOf'){if(pass.length===1)return null;if(pass.length>1)return{code:'ATA4002',keyword:'oneOf',instancePath:pp||'',path:pp||'',schemaPath:sp,message:'value matched '+pass.length+' of '+br.length+' oneOf variants, expected exactly one',params:{matched:pass.length,total:br.length}}}else{if(pass.length>=1)return null}let bi=0,bs=Infinity;for(let i=0;i<br.length;i++){const s=__ataScore(br[i].errors);if(s<bs){bs=s;bi=i}}const code=kw==='oneOf'?'ATA4001':'ATA4003';const best=br[bi];return{code,keyword:kw,instancePath:pp||'',path:pp||'',schemaPath:sp,message:'value matched 0 of '+br.length+' '+kw+' variants',params:{variants:br.length,closest:bi,closestName:best.title||('variant '+(bi+1))},branchErrors:best.errors}}")
+  }
   if (lines.length === 0) return (d) => ({ valid: true, errors: [] })
 
   const checkStr = lines.join('\n  ')
@@ -2560,6 +2604,39 @@ function compileToJSCodegenWithErrors(schema, schemaMap, userFormats) {
   }
 }
 
+// Emit codegen for oneOf/anyOf that runs each branch with error collection,
+// aggregates results, and uses __ataCollapse to surface a single best-branch
+// error. Wraps the existing per-branch evaluation; does not replace it.
+function emitBranchCollapse (branches, keyword, v, pathExpr, lines, ctx, schemaPrefix) {
+  ctx.usesBranchCollapse = true
+  const fi = ctx.varCounter++
+  const branchKw = keyword
+  const branchSp = schemaPrefix + '/' + branchKw
+  // Per-branch error-collecting functions, each returning {valid,errors}.
+  const fns = []
+  const titles = []
+  for (let i = 0; i < branches.length; i++) {
+    const sub = branches[i]
+    const subLines = []
+    const subSp = branchSp + '/' + i
+    if (typeof sub === 'object' && sub !== null) {
+      genCodeE(sub, '_bv', pathExpr, subLines, ctx, subSp)
+    }
+    const title = (sub && typeof sub === 'object' && typeof sub.title === 'string') ? sub.title : ''
+    titles.push(title)
+    const body = subLines.length === 0
+      ? `function(_bv){return{valid:true,errors:[]}}`
+      : `function(_bv){const _e=[];${subLines.join(';')};return{valid:_e.length===0,errors:_e}}`
+    fns.push(body)
+  }
+  const fnArr = `_brf${fi}`
+  const resArr = `_brr${fi}`
+  const titleArr = JSON.stringify(titles)
+  const collapsed = `_brc${fi}`
+  const pp = pathExpr || '""'
+  lines.push(`{const ${fnArr}=[${fns.join(',')}];const _bt${fi}=${titleArr};const ${resArr}=[];for(let _bi=0;_bi<${fnArr}.length;_bi++){const _br=${fnArr}[_bi](${v});${resArr}.push({valid:_br.valid,errors:_br.errors,title:_bt${fi}[_bi]})}const ${collapsed}=__ataCollapse('${branchKw}',${resArr},${pp},'${branchSp}');if(${collapsed}){_e.push(${collapsed});if(!_all)return{valid:false,errors:_e}}}`)
+}
+
 // Error-collecting code generator.
 // Instead of `return false`, pushes to `_e` array and optionally early-returns.
 // `_all` parameter: if falsy, return after first error.
@@ -2648,7 +2725,11 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
       }
     })
     const expected = types.join(', ')
-    lines.push(`if(!(${conds.join('||')})){_e.push({keyword:'type',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/type',params:{type:'${expected}'},message:'must be ${expected}'});if(!_all)return{valid:false,errors:_e}}`)
+    {
+      const typeSp = `${schemaPrefix}/type`
+      const lit = buildErrorLiteral({ keyword: 'type', schemaPath: typeSp, sourceMap: ctx.sourceMap })
+      lines.push(`if(!(${conds.join('||')})){_e.push({code:'${lit.codeStr}',keyword:'type',instancePath:${pathExpr||'""'},schemaPath:'${typeSp}',params:{type:'${expected}'},message:'must be ${expected}',docUrl:'${lit.docUrl}'${lit.frame}});if(!_all)return{valid:false,errors:_e}}`)
+    }
   }
 
   // In error mode, never assume type — always guard (data may have failed type check but allErrors continues)
@@ -2657,9 +2738,10 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
   const isStr = false
   const isNum = false
 
-  const fail = (keyword, schemaSuffix, paramsCode, msgCode) => {
+  const fail = (keyword, schemaSuffix, paramsCode, msgCode, fmt) => {
     const sp = schemaPrefix + '/' + schemaSuffix
-    return `_e.push({keyword:'${keyword}',instancePath:${pathExpr||'""'},schemaPath:'${sp}',params:${paramsCode},message:${msgCode}});if(!_all)return{valid:false,errors:_e}`
+    const lit = buildErrorLiteral({ keyword, format: fmt, schemaPath: sp, sourceMap: ctx.sourceMap })
+    return `_e.push({code:'${lit.codeStr}',keyword:'${keyword}',instancePath:${pathExpr||'""'},schemaPath:'${sp}',params:${paramsCode},message:${msgCode},docUrl:'${lit.docUrl}'${lit.frame}});if(!_all)return{valid:false,errors:_e}`
   }
 
   // enum
@@ -2692,8 +2774,10 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
   const requiredSet = new Set(schema.required || [])
   const hoisted = {}
   if (schema.required) {
+    const reqSp = `${schemaPrefix}/required`
+    const reqLit = buildErrorLiteral({ keyword: 'required', schemaPath: reqSp, sourceMap: ctx.sourceMap })
     for (const key of schema.required) {
-      lines.push(`if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})&&!(${JSON.stringify(key)} in ${v})){_e.push({keyword:'required',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/required',params:{missingProperty:'${esc(key)}'},message:"must have required property '${esc(key)}'"});if(!_all)return{valid:false,errors:_e}}`)
+      lines.push(`if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})&&!(${JSON.stringify(key)} in ${v})){_e.push({code:'${reqLit.codeStr}',keyword:'required',instancePath:${pathExpr||'""'},schemaPath:'${reqSp}',params:{missingProperty:'${esc(key)}'},message:"must have required property '${esc(key)}'",docUrl:'${reqLit.docUrl}'${reqLit.frame}});if(!_all)return{valid:false,errors:_e}}`)
     }
   }
 
@@ -2756,7 +2840,9 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
   }
   if (schema.format) {
     const fc = FORMAT_CODEGEN[schema.format]
-    const failPush = `_e.push({keyword:'format',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/format',params:{format:'${esc(schema.format)}'},message:'must match format "${esc(schema.format)}"'});if(!_all)return{valid:false,errors:_e}`
+    const fmtSp = `${schemaPrefix}/format`
+    const fmtLit = buildErrorLiteral({ keyword: 'format', format: schema.format, schemaPath: fmtSp, sourceMap: ctx.sourceMap })
+    const failPush = `_e.push({code:'${fmtLit.codeStr}',keyword:'format',instancePath:${pathExpr||'""'},schemaPath:'${fmtSp}',params:{format:'${esc(schema.format)}'},message:'must match format "${esc(schema.format)}"',docUrl:'${fmtLit.docUrl}'${fmtLit.frame}});if(!_all)return{valid:false,errors:_e}`
     // Format errors use the boolean codegen — just wrap with error push
     if (fc) {
       const ri = ctx.varCounter++
@@ -2816,15 +2902,19 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
   if (schema.additionalProperties === false && schema.properties) {
     const allowed = Object.keys(schema.properties).map(k => `${JSON.stringify(k)}`).join(',')
     const ci = ctx.varCounter++
-    const inner = `const _k${ci}=Object.keys(${v});const _a${ci}=new Set([${allowed}]);for(let _i=0;_i<_k${ci}.length;_i++){if(!_a${ci}.has(_k${ci}[_i])){_e.push({keyword:'additionalProperties',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/additionalProperties',params:{additionalProperty:_k${ci}[_i]},message:'must NOT have additional properties'});if(!_all)return{valid:false,errors:_e}}}`
+    const apSp = `${schemaPrefix}/additionalProperties`
+    const apLit = buildErrorLiteral({ keyword: 'additionalProperties', schemaPath: apSp, sourceMap: ctx.sourceMap })
+    const inner = `const _k${ci}=Object.keys(${v});const _a${ci}=new Set([${allowed}]);for(let _i=0;_i<_k${ci}.length;_i++){if(!_a${ci}.has(_k${ci}[_i])){_e.push({code:'${apLit.codeStr}',keyword:'additionalProperties',instancePath:${pathExpr||'""'},schemaPath:'${apSp}',params:{additionalProperty:_k${ci}[_i]},message:'must NOT have additional properties',docUrl:'${apLit.docUrl}'${apLit.frame}});if(!_all)return{valid:false,errors:_e}}}`
     lines.push(isObj ? `{${inner}}` : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
   }
 
   // dependentRequired
   if (schema.dependentRequired) {
+    const drSp = `${schemaPrefix}/dependentRequired`
+    const drLit = buildErrorLiteral({ keyword: 'dependentRequired', schemaPath: drSp, sourceMap: ctx.sourceMap })
     for (const [key, deps] of Object.entries(schema.dependentRequired)) {
       for (const dep of deps) {
-        lines.push(`if(typeof ${v}==='object'&&${v}!==null&&${JSON.stringify(key)} in ${v}&&!(${JSON.stringify(dep)} in ${v})){_e.push({keyword:'required',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/dependentRequired',params:{missingProperty:'${esc(dep)}'},message:"must have required property '${esc(dep)}'"});if(!_all)return{valid:false,errors:_e}}`)
+        lines.push(`if(typeof ${v}==='object'&&${v}!==null&&${JSON.stringify(key)} in ${v}&&!(${JSON.stringify(dep)} in ${v})){_e.push({code:'${drLit.codeStr}',keyword:'required',instancePath:${pathExpr||'""'},schemaPath:'${drSp}',params:{missingProperty:'${esc(dep)}'},message:"must have required property '${esc(dep)}'",docUrl:'${drLit.docUrl}'${drLit.frame}});if(!_all)return{valid:false,errors:_e}}`)
       }
     }
   }
@@ -2943,26 +3033,14 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
     }
   }
 
-  // anyOf
+  // anyOf - collapse to single best-branch error via __ataCollapse
   if (schema.anyOf) {
-    const fi = ctx.varCounter++
-    const fns = schema.anyOf.map((sub, i) => {
-      const subLines = []
-      genCode(sub, '_av', subLines, ctx)
-      return subLines.length === 0 ? `function(_av){return true}` : `function(_av){${subLines.join(';')};return true}`
-    })
-    lines.push(`{const _af${fi}=[${fns.join(',')}];let _am${fi}=false;for(let _ai=0;_ai<_af${fi}.length;_ai++){if(_af${fi}[_ai](${v})){_am${fi}=true;break}}if(!_am${fi}){${fail('anyOf', 'anyOf', '{}', "'must match a schema in anyOf'")}}}`)
+    emitBranchCollapse(schema.anyOf, 'anyOf', v, pathExpr, lines, ctx, schemaPrefix)
   }
 
-  // oneOf
+  // oneOf - collapse to single best-branch error via __ataCollapse
   if (schema.oneOf) {
-    const fi = ctx.varCounter++
-    const fns = schema.oneOf.map((sub, i) => {
-      const subLines = []
-      genCode(sub, '_ov', subLines, ctx)
-      return subLines.length === 0 ? `function(_ov){return true}` : `function(_ov){${subLines.join(';')};return true}`
-    })
-    lines.push(`{const _of${fi}=[${fns.join(',')}];let _oc${fi}=0;for(let _oi=0;_oi<_of${fi}.length;_oi++){if(_of${fi}[_oi](${v}))_oc${fi}++;if(_oc${fi}>1)break}if(_oc${fi}!==1){${fail('oneOf', 'oneOf', '{}', "'must match exactly one schema in oneOf'")}}}`)
+    emitBranchCollapse(schema.oneOf, 'oneOf', v, pathExpr, lines, ctx, schemaPrefix)
   }
 
   // not
@@ -3011,6 +3089,11 @@ function compileToJSCombined(schema, VALID_RESULT, schemaMap, userFormats) {
     // Bail on additionalProperties as a schema — combined path doesn't emit the
     // per-key sub-schema loop yet. The jsFn + errFn fallback handles it correctly.
     if (hasAdditionalPropertiesSchema(schema)) return null
+    // Bail on oneOf/anyOf — branch-collapse aggregation lives in genCodeE only.
+    // Letting genCodeC emit the legacy "must match exactly one" placeholder
+    // would short-circuit the ATA4001/ATA4002/ATA4003 contract. The boolean
+    // fast path plus errFn fallback handles these schemas with collapse.
+    if (s.includes('"oneOf"') || s.includes('"anyOf"')) return null
   }
   if (typeof schema === 'boolean') {
     return schema

package/lib/levenshtein.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// Bounded Levenshtein. Returns Infinity if distance > maxDistance.
+// Single-row DP. O(n*m) worst case but typical strings are <30 chars.
+function levenshtein (a, b, maxDistance) {
+  const max = maxDistance == null ? Infinity : maxDistance;
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return Infinity;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array(b.length + 1);
+  let curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+      if (curr[j] < rowMin) rowMin = curr[j];
+    }
+    if (rowMin > max) return Infinity;
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+module.exports = { levenshtein };

package/lib/render-compact.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const { color, ANSI, resolveColor, pathToDotted, trimCwd } = require('./render-shared');
+
+function renderCompact (errors, opts) {
+  if (!Array.isArray(errors) || errors.length === 0) return '';
+  opts = opts || {};
+  const useColor = resolveColor(opts.color || 'auto');
+  const cwd = opts.cwd;
+  const lines = [];
+
+  for (const err of errors) {
+    let prefix = '';
+    if (err.schemaSource) {
+      const f = trimCwd(err.schemaSource.file, cwd);
+      prefix = color(useColor, ANSI.cyan, `${f}:${err.schemaSource.line}:${err.schemaSource.col}`) + ' - ';
+    }
+    const codeStr = color(useColor, ANSI.red + ANSI.bold, `error ${err.code}`);
+    const pathStr = color(useColor, ANSI.cyan, pathToDotted(err.path));
+    const got = err.received != null ? `got ${err.received}` : '';
+    const sugg = err.suggestion ? color(useColor, ANSI.yellow, `, ${err.suggestion.text}`) : '';
+    const tail = got || sugg ? ` (${got}${sugg})` : '';
+    lines.push(`${prefix}${codeStr}: ${pathStr} ${err.message}${tail}`);
+  }
+
+  const n = errors.length;
+  lines.push('');
+  lines.push(`Found ${n} error${n === 1 ? '' : 's'} in ${opts.context || 'input'}.`);
+  if (!(process.stdout && process.stdout.isTTY)) {
+    lines.push('(run with --pretty for source frames)');
+  }
+  return lines.join('\n');
+}
+
+module.exports = { renderCompact };

package/lib/render-json.js

@@ -0,0 +1,12 @@
+'use strict';
+
+function renderJSON (errors, opts) {
+  opts = opts || {};
+  const payload = {
+    errors: Array.isArray(errors) ? errors : [],
+    summary: { count: Array.isArray(errors) ? errors.length : 0, context: opts.context || 'input' },
+  };
+  return opts.pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
+}
+
+module.exports = { renderJSON };

package/lib/render-pretty.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { color, ANSI, resolveColor, trimCwd, truncateLine, terminalWidth } = require('./render-shared');
+
+function caretLine (col, length, gutter) {
+  const pad = ' '.repeat(gutter);
+  const lead = ' '.repeat(Math.max(0, col - 1));
+  const carets = '^'.repeat(Math.max(1, length || 1));
+  return pad + '| ' + lead + carets;
+}
+
+function renderOne (err, useColor, opts) {
+  const lines = [];
+  const cwd = opts.cwd;
+  const width = terminalWidth();
+  const gutter = 3;
+
+  // Headline
+  const headline = `${err.message}`;
+  lines.push(color(useColor, ANSI.red + ANSI.bold, `error[${err.code}]: `) + headline);
+
+  // Schema source frame
+  if (err.schemaSource) {
+    const f = trimCwd(err.schemaSource.file, cwd);
+    lines.push(`  --> ${color(useColor, ANSI.cyan, `${f}:${err.schemaSource.line}:${err.schemaSource.col}`)}`);
+    lines.push('   |');
+    const ln = String(err.schemaSource.line).padStart(2, ' ');
+    const srcText = truncateLine(err.schemaSource.text, width - 8);
+    lines.push(` ${ln} | ${srcText}`);
+    const inlineHint = err.expected ? '  ' + color(useColor, ANSI.dim, `expected ${err.expected}`) : '';
+    lines.push(caretLine(err.schemaSource.col, 1, gutter) + inlineHint);
+    lines.push('   |');
+  }
+
+  // Data frame
+  if (err.dataFrame) {
+    lines.push(`  --> ${color(useColor, ANSI.dim, `input, byte ${err.dataFrame.byteOffset}`)}`);
+    lines.push('   |');
+    const ln = String(err.dataFrame.line).padStart(2, ' ');
+    const srcText = truncateLine(err.dataFrame.text, width - 8);
+    lines.push(` ${ln} | ${srcText}`);
+    const got = err.received != null ? '  ' + color(useColor, ANSI.dim, `got ${err.received}`) : '';
+    lines.push(caretLine(err.dataFrame.col, err.dataFrame.length, gutter) + got);
+    lines.push('   |');
+  }
+
+  if (err.suggestion) {
+    lines.push('   = ' + color(useColor, ANSI.yellow, 'help: ') + err.suggestion.text);
+  }
+  if (err.branchErrors && err.branchErrors.length) {
+    const variant = (err.params && err.params.closestName) || 'closest variant';
+    const n = err.branchErrors.length;
+    lines.push('   = ' + color(useColor, ANSI.dim, 'note: ') + `closest match was ${variant} with ${n} error${n === 1 ? '' : 's'}:`);
+    renderBranchErrors(err.branchErrors, 1, lines, useColor);
+  }
+  if (err.docUrl) {
+    lines.push('   = ' + color(useColor, ANSI.dim, 'note: see ') + err.docUrl);
+  }
+  return lines.join('\n');
+}
+
+// Render nested branchErrors with a depth cap. Stops recursing past depth 3
+// and emits a placeholder. Keeps pretty output bounded for deeply nested
+// oneOf chains while preserving the structured payload for JSON consumers.
+function renderBranchErrors (subs, depth, lines, useColor) {
+  if (depth >= 3) {
+    lines.push('       ' + color(useColor, ANSI.dim, '... deeper branch errors omitted, see structured output'));
+    return;
+  }
+  const max = 3;
+  const shown = subs.slice(0, max);
+  for (const sub of shown) {
+    lines.push('       ' + color(useColor, ANSI.dim, `${sub.keyword}: ${sub.message || ''}`));
+    if (sub.branchErrors && sub.branchErrors.length) renderBranchErrors(sub.branchErrors, depth + 1, lines, useColor);
+  }
+  if (subs.length > max) {
+    lines.push('       ' + color(useColor, ANSI.dim, `... and ${subs.length - max} more`));
+  }
+}
+
+function renderPretty (errors, opts) {
+  if (!Array.isArray(errors) || errors.length === 0) return '';
+  opts = opts || {};
+  const useColor = resolveColor(opts.color || 'auto');
+  const maxErrors = opts.maxErrors != null ? opts.maxErrors : 20;
+  const context = opts.context || 'input';
+
+  const blocks = [];
+  const limit = maxErrors === 0 ? errors.length : Math.min(maxErrors, errors.length);
+  for (let i = 0; i < limit; i++) {
+    blocks.push(renderOne(errors[i], useColor, opts));
+  }
+  let out = blocks.join('\n\n');
+  if (limit < errors.length) {
+    out += `\n\n... and ${errors.length - limit} more errors (run with --pretty --max-errors=0 to see all)`;
+  }
+  const n = errors.length;
+  out += `\n\n` + color(useColor, ANSI.red + ANSI.bold, `error: `) + `${n} schema violation${n === 1 ? '' : 's'} in ${context}`;
+  return out;
+}
+
+module.exports = { renderPretty };

package/lib/render-shared.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+};
+
+function resolveColor (opt) {
+  if (opt === 'never') return false;
+  if (opt === 'always') return true;
+  if (process.env.NO_COLOR != null && process.env.NO_COLOR !== '') return false;
+  const fc = process.env.FORCE_COLOR;
+  if (fc === '1' || fc === '2' || fc === '3' || fc === 'true') return true;
+  return !!(process.stdout && process.stdout.isTTY);
+}
+
+function color (enabled, code, s) {
+  return enabled ? code + s + ANSI.reset : s;
+}
+
+function pathToDotted (jsonPointer) {
+  if (!jsonPointer || jsonPointer === '/') return 'body';
+  const parts = jsonPointer.replace(/^\//, '').split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let out = 'body';
+  for (const p of parts) {
+    if (/^[0-9]+$/.test(p)) {
+      out += '[' + p + ']';
+    } else if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(p)) {
+      out += '.' + p;
+    } else {
+      out += '[' + JSON.stringify(p) + ']';
+    }
+  }
+  return out;
+}
+
+function trimCwd (file, cwd) {
+  if (!file) return file;
+  const c = cwd || process.cwd();
+  if (file.startsWith(c + '/')) return file.slice(c.length + 1);
+  return file;
+}
+
+function truncateLine (text, maxWidth) {
+  if (!text || text.length <= maxWidth) return text;
+  return text.slice(0, maxWidth - 1) + '…';
+}
+
+function terminalWidth () {
+  const w = process.stdout && process.stdout.columns;
+  return (typeof w === 'number' && w > 0) ? w : 100;
+}
+
+module.exports = { ANSI, resolveColor, color, pathToDotted, trimCwd, truncateLine, terminalWidth };