ata-validator 0.14.0 → 0.15.0

package/lib/source-positions.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * Build a map of JSON pointer → { line, col, text } by scanning JSON text.
+ *
+ * Approach: use JSON.parse for correctness, then do one structural scan
+ * tracking bracket depth and key positions. This avoids hand-rolling a
+ * full JSON parser while delivering keyword-level positions sufficient
+ * for source frames.
+ *
+ * Limitations (acceptable for source frames):
+ *  - Duplicate keys: last wins.
+ *  - Whitespace inside string values does not affect tracking (strings
+ *    are skipped over wholesale).
+ *  - Comments / trailing commas: JSON only, no JSON5.
+ */
+
+function escapePtr (s) {
+  return s.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
+function buildPositionMap (text) {
+  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) {
+    // Binary search lineStart
+    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 () {
+    // Assumes text[i] === '"'
+    const start = i;
+    i++;
+    while (i < n) {
+      const ch = text.charCodeAt(i);
+      if (ch === 0x5c) { i += 2; continue; }   // backslash escape
+      if (ch === 0x22) { i++; return JSON.parse(text.slice(start, i)); }
+      i++;
+    }
+    throw new Error('unterminated string at offset ' + start);
+  }
+
+  function skipValue () {
+    skipWs();
+    if (i >= n) return;
+    const ch = text.charCodeAt(i);
+    if (ch === 0x22) { readString(); return; }
+    if (ch === 0x7b || ch === 0x5b) { // { or [
+      const open = ch;
+      const close = open === 0x7b ? 0x7d : 0x5d;
+      let depth = 1;
+      i++;
+      while (i < n && depth > 0) {
+        const c = text.charCodeAt(i);
+        if (c === 0x22) { readString(); continue; }
+        if (c === open) depth++;
+        else if (c === close) depth--;
+        i++;
+      }
+      return;
+    }
+    // primitive: read until ,, }, ], or whitespace
+    while (i < n) {
+      const c = text.charCodeAt(i);
+      if (c === 0x2c || c === 0x7d || c === 0x5d || c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) return;
+      i++;
+    }
+  }
+
+  function pointerOf (path) {
+    if (path.length === 0) return '';
+    return '/' + path.map(escapePtr).join('/');
+  }
+
+  function walk (path) {
+    skipWs();
+    if (i >= n) return;
+    // Record position of the *value* at this path
+    const pos = offsetToLineCol(i);
+    map[pointerOf(path)] = pos;
+
+    const ch = text.charCodeAt(i);
+
+    if (ch === 0x7b) { // object
+      i++;
+      while (true) {
+        skipWs();
+        if (text.charCodeAt(i) === 0x7d) { i++; return; }
+        if (text.charCodeAt(i) === 0x2c) { i++; continue; }
+        skipWs();
+        // Key
+        const keyStart = i;
+        const key = readString();
+        // Record key position too — keyed by `<path>/<key>` so source frame
+        // can point at the keyword name, not its value.
+        const keyPos = offsetToLineCol(keyStart);
+        skipWs();
+        if (text.charCodeAt(i) !== 0x3a) throw new Error('expected ":" at offset ' + i);
+        i++;
+        const childPath = path.concat([key]);
+        // Mark the key location at <path>/<key>#key (used by renderers
+        // for keyword-name framing); the value location overwrites in walk().
+        map[pointerOf(childPath) + '#key'] = keyPos;
+        walk(childPath);
+      }
+    } else if (ch === 0x5b) { // array
+      i++;
+      let idx = 0;
+      while (true) {
+        skipWs();
+        if (text.charCodeAt(i) === 0x5d) { i++; return; }
+        if (text.charCodeAt(i) === 0x2c) { i++; continue; }
+        walk(path.concat([String(idx)]));
+        idx++;
+      }
+    } else {
+      skipValue();
+    }
+  }
+
+  // Strip BOM if present
+  if (text.charCodeAt(0) === 0xfeff) i = 1;
+
+  walk([]);
+  return map;
+}
+
+module.exports = { buildPositionMap, escapePtr };

package/lib/suggestions.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { levenshtein } = require('./levenshtein');
+
+// Hand-coded format hints. Keep <=60 chars per text.
+const FORMAT_HINTS = {
+  email: (val) => {
+    if (typeof val !== 'string') return null;
+    if (!val.includes('@')) return "missing '@' and domain part";
+    if (val.split('@').length > 2) return "multiple '@' characters";
+    const [, dom] = val.split('@');
+    if (!dom || !dom.includes('.')) return 'domain part missing dot';
+    return null;
+  },
+  date: (val) => {
+    if (typeof val !== 'string') return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(val);
+    if (!m) return 'expected YYYY-MM-DD layout';
+    const mo = +m[2]; if (mo < 1 || mo > 12) return 'month must be 01-12';
+    const d = +m[3]; if (d < 1 || d > 31) return 'day must be 01-31';
+    return null;
+  },
+  uuid: (val) => {
+    if (typeof val !== 'string') return null;
+    if (!/^[0-9a-fA-F-]+$/.test(val)) return 'expected hex digits and dashes';
+    return 'expected 8-4-4-4-12 hex layout';
+  },
+  ipv4: (val) => typeof val === 'string' ? 'expected four 0-255 octets separated by dots' : null,
+};
+
+function suggestEnumTypo (received, enumValues) {
+  if (typeof received !== 'string') return null;
+  if (!Array.isArray(enumValues) || enumValues.length === 0 || enumValues.length > 30) return null;
+  let best = null;
+  let bestDist = Infinity;
+  let tied = false;
+  for (const v of enumValues) {
+    if (typeof v !== 'string') continue;
+    const d = levenshtein(received, v, 2);
+    if (d < bestDist) { best = v; bestDist = d; tied = false; }
+    else if (d === bestDist) tied = true;
+  }
+  if (best && bestDist <= 2 && !tied) {
+    return { text: `did you mean \`${best}\`?`, kind: 'typo' };
+  }
+  return null;
+}
+
+function suggestRequiredTypo (missing, presentKeys) {
+  if (!missing || !Array.isArray(presentKeys)) return null;
+  for (const k of presentKeys) {
+    if (typeof k !== 'string') continue;
+    const d = levenshtein(missing, k, 2);
+    if (d <= 2 && d > 0) {
+      return { text: `did you mean \`${missing}\` instead of \`${k}\`?`, kind: 'similar-key' };
+    }
+  }
+  return null;
+}
+
+function suggestFormat (format, received) {
+  const fn = FORMAT_HINTS[format];
+  if (!fn) return null;
+  // received is repr-truncated string like '"foo"'; unwrap for testing
+  let raw = received;
+  if (typeof raw === 'string' && raw.startsWith('"') && raw.endsWith('"')) {
+    try { raw = JSON.parse(raw); } catch {}
+  }
+  const text = fn(raw);
+  return text ? { text, kind: 'format' } : null;
+}
+
+function suggestCoercion (expectedType, received) {
+  if (typeof received !== 'string' || !received.startsWith('"') || !received.endsWith('"')) return null;
+  let raw;
+  try { raw = JSON.parse(received); } catch { return null; }
+  if (typeof raw !== 'string') return null;
+  if (expectedType === 'integer' && /^-?\d+$/.test(raw)) {
+    return { text: 'value would coerce; enable `coerceTypes` or pass an integer', kind: 'coercion' };
+  }
+  if (expectedType === 'number' && /^-?\d+(\.\d+)?$/.test(raw)) {
+    return { text: 'value would coerce; enable `coerceTypes` or pass a number', kind: 'coercion' };
+  }
+  if (expectedType === 'boolean' && (raw === 'true' || raw === 'false')) {
+    return { text: 'value would coerce; enable `coerceTypes` or pass a boolean', kind: 'coercion' };
+  }
+  return null;
+}
+
+/**
+ * Apply suggestion sources in priority order. Returns the first hit, or null.
+ * @param err Enriched ValidationError (with `received`, `params`, `keyword`)
+ * @param data The full input data (for required-typo)
+ */
+function suggestFor (err, data) {
+  if (err.keyword === 'enum') {
+    return suggestEnumTypo(parseReceived(err.received), err.params && err.params.allowedValues);
+  }
+  if (err.keyword === 'required') {
+    const missing = err.params && err.params.missingProperty;
+    let parentPath = err.path || '';
+    if (parentPath.endsWith('/' + missing)) parentPath = parentPath.slice(0, -missing.length - 1);
+    const parent = walk(data, parentPath);
+    if (parent && typeof parent === 'object') {
+      return suggestRequiredTypo(missing, Object.keys(parent));
+    }
+    return null;
+  }
+  if (err.keyword === 'format') {
+    return suggestFormat(err.params && err.params.format, err.received);
+  }
+  if (err.keyword === 'type') {
+    return suggestCoercion(err.params && err.params.type, err.received);
+  }
+  return null;
+}
+
+function parseReceived (r) {
+  if (typeof r !== 'string') return r;
+  if (r.startsWith('"') && r.endsWith('"')) { try { return JSON.parse(r); } catch { return r; } }
+  return r;
+}
+
+function walk (data, pointer) {
+  if (!pointer) return data;
+  const parts = pointer.replace(/^\//, '').split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = data;
+  for (const p of parts) { if (cur == null) return undefined; cur = cur[p]; }
+  return cur;
+}
+
+module.exports = { suggestFor, suggestEnumTypo, suggestRequiredTypo, suggestFormat, suggestCoercion };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ata-validator",
-  "version": "0.14.0",
-  "description": "Ultra-fast JSON Schema validator. 5x faster validation, 159,000x faster compilation. Works without native addon. Cross-schema $ref, Draft 2020-12 + Draft 7, V8-optimized JS codegen, simdjson, RE2, multi-core. Standard Schema V1 compatible.",
+  "version": "0.15.0",
+  "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
   "types": "index.d.ts",
@@ -36,12 +36,14 @@
   },
   "scripts": {
     "install": "node scripts/install.js",
-    "prepublishOnly": "node scripts/check-prebuilds.js",
+    "prepublishOnly": "node scripts/check-prebuilds.js && ATA_ALLOW_DOC_PLACEHOLDERS=1 node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js",
+    "release:check": "node scripts/check-prebuilds.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js",
     "build": "cmake-js build --target ata",
     "rebuild": "cmake-js rebuild --target ata",
     "prebuild": "pkg-prebuilds-copy --baseDir build/Release --source ata.node --name=ata --strip --napi_version=10",
     "prebuild-all": "npm run prebuild -- --arch x64 && npm run prebuild -- --arch arm64",
-    "test": "node test.js && node tests/test_no_native.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_typed_validator_runner.js",
+    "test": "node test.js && node tests/test_no_native.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_typed_validator_runner.js && node tests/test_error_codes_lock.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node benchmark/bench_aot_size.mjs",
+    "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js",
     "test:compat": "node tests/test_compat.js",
     "test:standard-schema": "node tests/test_standard_schema.js",
@@ -128,6 +130,7 @@
     "@sinclair/typebox": "^0.34.49",
     "@types/node": "^25.8.0",
     "cmake-js": "^8.0.0",
+    "jsonc-parser": "^3.3.1",
     "mitata": "^1.0.34",
     "typebox": "^1.1.7",
     "typescript": "^6.0.3",

package/scripts/check-doc-coverage.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { all } = require('../lib/error-codes');
+
+const doc = fs.readFileSync(path.join(__dirname, '..', 'docs', 'error-codes.md'), 'utf8');
+
+const missing = [];
+const placeholder = [];
+for (const code of all()) {
+  const headingRe = new RegExp(`^### ${code} `, 'm');
+  if (!headingRe.test(doc)) {
+    missing.push(code);
+    continue;
+  }
+  // Find the section, ensure it doesn't still say "_TODO — fill before release._"
+  const start = doc.search(headingRe);
+  const next = doc.slice(start + 4).search(/^### /m);
+  const section = next === -1 ? doc.slice(start) : doc.slice(start, start + 4 + next);
+  if (section.includes('_TODO')) placeholder.push(code);
+}
+
+if (missing.length) {
+  console.error(`docs/error-codes.md is missing entries for: ${missing.join(', ')}`);
+  process.exit(1);
+}
+if (placeholder.length && process.env.ATA_ALLOW_DOC_PLACEHOLDERS !== '1') {
+  console.error(`docs/error-codes.md has placeholder _TODO sections for: ${placeholder.join(', ')}`);
+  console.error('Run: ATA_ALLOW_DOC_PLACEHOLDERS=1 node scripts/check-doc-coverage.js (development only)');
+  process.exit(1);
+}
+console.log(`ok: ${all().length} codes documented`);

package/scripts/regen-error-codes-doc.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CODES, all } = require('../lib/error-codes');
+
+const lines = [];
+lines.push('# ata Error Codes');
+lines.push('');
+lines.push('Stable registry of `ATA####` codes emitted by ata-validator. Each section is the target of `https://ata-validator.com/e/<code>`.');
+lines.push('');
+
+const byCategory = {};
+for (const c of all()) {
+  const cat = CODES[c].category;
+  (byCategory[cat] ||= []).push(c);
+}
+
+const order = ['type', 'shape', 'constraint', 'format', 'enum', 'composition', 'ref', 'system'];
+for (const cat of order) {
+  if (!byCategory[cat]) continue;
+  lines.push(`## ${cat}`);
+  lines.push('');
+  for (const code of byCategory[cat]) {
+    const meta = CODES[code];
+    lines.push(`### ${code} — ${meta.headline}`);
+    lines.push('');
+    lines.push(`Keyword: \`${meta.keyword}\`${meta.format ? ` (format: \`${meta.format}\`)` : ''}`);
+    lines.push('');
+    lines.push('**Cause.** _TODO — fill before release._');
+    lines.push('');
+    lines.push('**Fix.** _TODO — fill before release._');
+    lines.push('');
+  }
+}
+
+const docPath = path.join(__dirname, '..', 'docs', 'error-codes.md');
+fs.writeFileSync(docPath, lines.join('\n') + '\n');
+console.log(`wrote ${all().length} sections to docs/error-codes.md`);

package/scripts/regen-lock.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CODES, all } = require('../lib/error-codes');
+
+const out = {};
+for (const c of all()) {
+  out[c] = {
+    keyword: CODES[c].keyword,
+    category: CODES[c].category,
+    format: CODES[c].format || null,
+  };
+}
+
+const lockPath = path.join(__dirname, '..', 'tests', 'error-codes.lock.json');
+fs.writeFileSync(lockPath, JSON.stringify(out, null, 2) + '\n');
+console.log(`wrote ${all().length} codes to ${path.relative(process.cwd(), lockPath)}`);