ata-validator 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 0.15.1 - 2026-05-23
+
+### Fixed
+
+- Coercion, defaults, and `removeAdditional` now follow a cross-schema `$ref` to the referenced shape. A whole-schema reference like `{ $ref: 'shared#' }` (used for shared route schemas) or a property reference like `{ id: { $ref: 'shared#/properties/id' } }` is preprocessed instead of skipped.
+- The compile cache now keys on referenced schema content, not just the `$id`. Two validators that share a root schema string and an `$id` pointing at different schemas no longer reuse the wrong compiled function.
+
+## 0.15.0 - 2026-05-18
+
+### Added
+
+- **Compiler-grade error output.** Every validation error now carries a stable `code` (`ATA####`), an `expected`/`received` pair, a `docUrl`, and, when the input came in as a JSON string or Buffer, a `dataFrame` pointing at the offending bytes. The full registry of 46 codes lives at [`docs/error-codes.md`](docs/error-codes.md) with permalinks at `https://ata-validator.com/e/<CODE>`.
+- **Renderer API.** `renderPretty`, `renderCompact`, and `renderJSON` are exported from `ata-validator`. Pretty output mirrors rustc-style code frames with carets, help, and note lines; compact collapses to one line per error; JSON is structured for tooling.
+- **`ata validate` subcommand.** `ata validate <schema> <data>` runs a schema against a JSON data file and prints renderer output. TTY auto-renders pretty; pipes default to compact; `--format=json` returns structured output. `--pretty`, `--compact`, `--max-errors`, `--color`, `--no-color` cover the rest of the surface.
+- **Runtime source maps.** `new Validator(schema, { source: { path, content } })` attaches per-error `schemaSource` (file, line, col, text) by re-parsing the schema with a position-aware scanner.
+- **AOT source maps.** AOT-compiled validators carry the structured error fields (`code`, `docUrl`) and embed per-error `schemaSource` when built with the source map enabled. On by default in development, off when `NODE_ENV=production` or `--no-source` is passed.
+- **`ata compile` / `ata build` flags.** New `--source` / `--no-source` flags. `ata build --dual` emits both a source-mapped artifact (`*.compiled.mjs`) and a stripped one (`*.compiled.min.mjs`) in a single run.
+- **Size budget gate.** `npm run bench:size` enforces a gzipped-byte budget over the AOT codegen output to catch silent bundle bloat. Baseline at `benchmark/baselines/aot-size.json`, gates derive from the baseline with 1.5x headroom.
+- **`oneOf` / `anyOf` collapse.** Branching failures collapse to a single best-branch error (`ATA4001` / `ATA4002` / `ATA4003`) instead of the full branch-tree. The closest matching variant's errors are still available under `branchErrors`. `allOf` errors continue to surface every failing branch.
+- **Suggestions.** A new `suggestion` field nudges users when ata is confident: typo against enum, missing-required typo, format-violation hint, type-coercion nudge. Runtime validators populate automatically; AOT validators expose `attachSuggestions(errors, data)` to keep AOT bundles small.
+- **`richErrors: false` opt-out.** `new Validator(schema, { richErrors: false })` preserves the v0.14 error shape byte-for-byte. `abortEarly: true` continues to short-circuit; the returned error carries `code: 'ATA9000'` and no enrichment.
+- **`release:check` npm script.** Runs the prebuilds, doc-coverage, and error-code lockfile checks in strict mode before a publish.
+
+### Changed
+
+- `prepublishOnly` now chains `check-prebuilds`, `check-doc-coverage` (lenient until per-code prose lands), and the error-code lockfile test.
+- `ata compile` and `ata build` failures route through the renderer with code `ATA9002`, so command-line schema errors look the same as runtime ones.
+
+### Notes
+
+- **Log scrapers**: errors now carry `code`, `dataFrame`, `suggestion`, and `docUrl` fields. If you serialize `result.errors` directly into logs, line size will grow. Pass `richErrors: false` for the v0.14 shape, or pipe through `renderCompact` for a stable one-line format.
+- **AOT bundle size**: source-mapped variants (`.compiled.mjs`) add up to 200 bytes gzipped for a 10-field schema. Production builds (`NODE_ENV=production` or `--no-source`) emit the no-source variant. Use `ata build --dual` to emit both.
+- **Fastify**: a companion `fastify-ata` release wires the new format into route error responses.
+
 ## 0.14.0 - 2026-05-16
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # ata-validator
 
-Compile JSON Schema files into per-schema ESM modules at build time. Drop the runtime validator from your production bundle. Optional runtime API for dynamic schemas.
+JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile your schemas to per-schema ESM modules with no validator dependency. `Validator<T>` composes with TypeBox, Zod-from-JSON-Schema, Valibot, or hand-written types. Runtime API available for dynamic schemas.
 
 [![npm](https://img.shields.io/npm/v/ata-validator)](https://www.npmjs.com/package/ata-validator)
 [![License](https://img.shields.io/npm/l/ata-validator)](LICENSE)
@@ -39,6 +39,41 @@ Reproduce on your machine with `npm run bench:aot-vs-ajv`. Numbers measured on A
 
 The wins are largest on bundle size and compile time because AOT moves work from runtime to build time. Throughput and cold start are also faster because the compiled validator is a tight straight-line function with no schema-walk overhead.
 
+## Error messages
+
+ata's error output is compiler-grade: each error carries a stable code, an inline source frame pointing at the schema file, and another pointing at the offending bytes in the request payload. Renderers ship in three styles:
+
+```ts
+import { Validator, renderPretty, renderCompact, renderJSON } from 'ata-validator'
+
+const v = new Validator(schema, { source: { path: 'schemas/user.json', content: schemaText } })
+const r = v.validateJSON(input)
+if (!r.valid) {
+  console.error(renderPretty(r.errors))
+  // error[ATA3001]: value does not match format "email"
+  //   --> schemas/user.json:5:7
+  //    |
+  //  5 |       "email": { "type": "string", "format": "email" }
+  //    |       ^^^^^^^  expected format 'email'
+  //    |
+  //   --> input, byte 23
+  //    |
+  //  1 | {"name":"M","email":"not-an-email","age":-3}
+  //    |                     ^^^^^^^^^^^^^^  got "not-an-email"
+  //    |
+  //    = help: missing '@' and domain part
+  //    = note: see https://ata-validator.com/e/ATA3001
+}
+```
+
+The `ata` CLI ships `ata validate <schema> <data>` for one-off checks. TTY auto-renders pretty; pipes default to compact; `--format=json` produces structured output for tooling.
+
+Errors carry a stable `code` field (`ATA####`), see the [error code registry](docs/error-codes.md). Each code has a permalink at `https://ata-validator.com/e/<CODE>`.
+
+### Opting out
+
+For consumers who built log dashboards on the v0.14 error shape, `new Validator(schema, { richErrors: false })` returns the legacy shape exactly. For high-throughput paths, `abortEarly: true` continues to short-circuit; the returned error carries `code: 'ATA9000'` and no enrichment.
+
 ## When to use the runtime API instead
 
 `ata build` is for schemas you know at build time. If your schemas are user-supplied at runtime (form builders, no-code platforms, dynamic API ingestion), use the runtime API:

package/bin/ata.js

@@ -8,8 +8,17 @@ function usage() {
   process.stdout.write(`ata-validator CLI
 
 Usage:
-  ata compile <schema-file> [options]   Compile one schema to a standalone module.
-  ata build   <glob>...    [options]    Compile a project's schemas (glob pattern) per file.
+  ata compile  <schema-file> [options]  Compile one schema to a standalone module.
+  ata build    <glob>...     [options]  Compile a project's schemas (glob pattern) per file.
+  ata validate <schema> <data> [options] Validate a JSON data file against a schema.
+
+Validate options:
+  --pretty                Render errors with source frames (default on TTY)
+  --compact               Render errors as one line each (default when piped)
+  --format <fmt>          Output format: pretty | compact | json
+  --max-errors <n>        Limit pretty output to N errors (0 = no limit). Default: 20
+  --color <when>          Color output: auto | always | never. Default: auto
+  --no-color              Disable color output (alias for --color=never)
 
 Compile options:
   -o, --output <file>     Output path. Default: <schema-file>.validator.mjs
@@ -17,6 +26,8 @@ Compile options:
   --name <TypeName>       Name of the top-level type in .d.ts. Default: inferred from filename
   --no-types              Skip .d.ts generation
   --abort-early           Use stub errors (smallest bundle)
+  --source                Embed schema source map (default in development)
+  --no-source             Omit source map (default in production, NODE_ENV=production)
 
 Build options:
   --out-dir <dir>         Write outputs into this directory instead of alongside sources
@@ -29,6 +40,9 @@ Build options:
   --strict                Treat any AOT-incompatible schema as a build error (default: skip + warn)
   --watch                 Re-emit on schema change (Ctrl-C to exit)
   --no-types              Skip .d.mts/.d.cts emission alongside compiled modules
+  --source                Embed schema source map (default in development)
+  --no-source             Omit source map (default in production, NODE_ENV=production)
+  --dual                  Emit both .compiled.mjs (with source) and .compiled.min.mjs (without)
 
   -h, --help              Show this message
 
@@ -36,11 +50,25 @@ Examples:
   ata compile schemas/user.json -o src/generated/user.validator.mjs
   ata build 'schemas/*.json'
   ata build 'src/**/*.schema.json' --out-dir build/validators
+  ata validate schemas/user.json payload.json --pretty
 `);
 }
 
 function parseArgs(argv) {
   const out = { _: [], opts: {} };
+  // Normalize --key=value into --key value pairs so equals-form is accepted
+  // for every option without per-option branches below.
+  const normalized = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--') && a.includes('=')) {
+      const eq = a.indexOf('=');
+      normalized.push(a.slice(0, eq), a.slice(eq + 1));
+    } else {
+      normalized.push(a);
+    }
+  }
+  argv = normalized;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '-h' || a === '--help') { out.opts.help = true; continue; }
@@ -64,12 +92,34 @@ function parseArgs(argv) {
       continue;
     }
     if (a === '--watch') { out.opts.watch = true; continue; }
+    if (a === '--source') { out.opts.source = true; continue; }
+    if (a === '--no-source') { out.opts.source = false; continue; }
+    if (a === '--dual') { out.opts.dual = true; continue; }
+    if (a === '--pretty') { out.opts.pretty = true; continue; }
+    if (a === '--compact') { out.opts.compact = true; continue; }
+    if (a === '--no-color') { out.opts.noColor = true; continue; }
+    if (a === '--color') { out.opts.color = argv[++i]; continue; }
+    if (a === '--max-errors') {
+      const v = argv[++i];
+      const n = Number(v);
+      if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
+        throw new Error(`--max-errors requires a non-negative integer (got "${v}")`);
+      }
+      out.opts.maxErrors = n;
+      continue;
+    }
     if (a.startsWith('-')) { throw new Error(`Unknown option: ${a}`); }
     out._.push(a);
   }
   return out;
 }
 
+function resolveSourceDefault (opts) {
+  if (opts.source === true) return true;
+  if (opts.source === false) return false;
+  return process.env.NODE_ENV !== 'production';
+}
+
 function inferOutput(inputPath, format) {
   const dir = path.dirname(inputPath);
   const base = path.basename(inputPath, path.extname(inputPath));
@@ -77,6 +127,27 @@ function inferOutput(inputPath, format) {
   return path.join(dir, base + ext);
 }
 
+// Renders a schema-compile failure through the structured error pipeline so
+// `ata compile` / `ata build` surface the same look-and-feel as runtime
+// validation errors. The actual position of the schema flaw isn't known here
+// (parsing or codegen already bailed), so schemaSource is left undefined.
+function reportCompileError (schemaFile, message) {
+  const { renderPretty, renderCompact } = require('..');
+  const fmt = process.stdout.isTTY ? 'pretty' : 'compact';
+  const err = {
+    code: 'ATA9002',
+    keyword: '__compile__',
+    path: '',
+    message,
+    schemaSource: undefined,
+    docUrl: 'https://ata-validator.com/e/ATA9002',
+  };
+  const out = fmt === 'pretty'
+    ? renderPretty([err], { color: 'auto', context: schemaFile })
+    : renderCompact([err], { color: 'auto', context: schemaFile });
+  process.stderr.write(out + '\n');
+}
+
 function cmdCompile(args) {
   if (args._.length === 0) {
     process.stderr.write('error: missing <schema-file>\n\n');
@@ -96,7 +167,7 @@ function cmdCompile(args) {
   try {
     schemaStr = fs.readFileSync(input, 'utf8');
   } catch (e) {
-    process.stderr.write(`error: cannot read ${input}: ${e.message}\n`);
+    reportCompileError(input, `cannot read ${input}: ${e.message}`);
     process.exit(1);
   }
 
@@ -104,15 +175,32 @@ function cmdCompile(args) {
   try {
     schema = JSON.parse(schemaStr);
   } catch (e) {
-    process.stderr.write(`error: ${input} is not valid JSON: ${e.message}\n`);
+    reportCompileError(input, `${input} is not valid JSON: ${e.message}`);
     process.exit(1);
   }
 
   const { Validator } = require('..');
-  const v = new Validator(schema);
-  const src = v.toStandaloneModule({ format, abortEarly });
+  let v;
+  try {
+    v = new Validator(schema);
+  } catch (e) {
+    reportCompileError(input, e.message);
+    process.exit(1);
+  }
+  const source = resolveSourceDefault(args.opts);
+  let sourceMap = null;
+  if (source) {
+    try {
+      const { buildPositionMap } = require('../lib/source-positions');
+      sourceMap = buildPositionMap(schemaStr);
+    } catch {
+      sourceMap = null;
+    }
+  }
+  const schemaFile = path.relative(process.cwd(), input) || input;
+  const src = v.toStandaloneModule({ format, abortEarly, source, sourceMap, schemaFile });
   if (!src) {
-    process.stderr.write('error: schema is too complex for standalone compilation\n');
+    reportCompileError(input, 'schema is too complex for standalone compilation');
     process.exit(1);
   }
 
@@ -165,6 +253,9 @@ function cmdBuild(args) {
     strict: !!args.opts.strict,
     types: args.opts.types,
     cacheFile: args.opts.cacheFile,
+    // Forward the explicit user choice (true / false / undefined). The
+    // aot-build module applies the NODE_ENV-aware default when undefined.
+    source: args.opts.source,
   };
 
   const printReport = (report) => {
@@ -182,7 +273,7 @@ function cmdBuild(args) {
       process.stdout.write(`ata: skipped ${s.input}: ${s.reason}\n`);
     }
     for (const f of report.failed) {
-      process.stderr.write(`ata: failed  ${f.input}: ${f.error}\n`);
+      reportCompileError(f.input, f.error);
     }
   };
 
@@ -199,16 +290,96 @@ function cmdBuild(args) {
     return;
   }
 
-  buildLib.build(buildOpts).then((report) => {
-    printReport(report);
-    if (args.opts.check && report.staleCount > 0) process.exit(1);
-    if (report.failed.length > 0) process.exit(1);
-  }).catch((e) => {
+  // --dual emits two artifacts per schema: one source-mapped (default suffix)
+  // and one stripped (suffix .compiled.min). Useful for shipping both a
+  // developer-friendly bundle and a production-lean one from a single build.
+  const dual = !!args.opts.dual;
+  const runs = dual
+    ? [
+      { ...buildOpts, source: true, suffix: args.opts.suffix || '.compiled' },
+      { ...buildOpts, source: false, suffix: (args.opts.suffix || '.compiled') + '.min' },
+    ]
+    : [buildOpts];
+
+  (async () => {
+    let anyFailed = false;
+    let anyStale = false;
+    for (const run of runs) {
+      const report = await buildLib.build(run);
+      printReport(report);
+      if (args.opts.check && report.staleCount > 0) anyStale = true;
+      if (report.failed.length > 0) anyFailed = true;
+    }
+    if (anyFailed || anyStale) process.exit(1);
+  })().catch((e) => {
     process.stderr.write(`error: ${e.message}\n`);
     process.exit(1);
   });
 }
 
+function cmdValidate (args) {
+  if (args._.length < 2) {
+    process.stderr.write('error: ata validate <schema> <data-file>\n');
+    process.exit(2);
+  }
+  const [schemaPath, dataPath] = args._;
+
+  let schemaContent;
+  try {
+    schemaContent = fs.readFileSync(schemaPath, 'utf8');
+  } catch (e) {
+    process.stderr.write(`error: cannot read ${schemaPath}: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  let schema;
+  try {
+    schema = JSON.parse(schemaContent);
+  } catch (e) {
+    process.stderr.write(`error: ${schemaPath} is not valid JSON: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  let data;
+  try {
+    data = fs.readFileSync(dataPath, 'utf8');
+  } catch (e) {
+    process.stderr.write(`error: cannot read ${dataPath}: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  const { Validator, renderPretty, renderCompact, renderJSON } = require('..');
+  let v;
+  try {
+    v = new Validator(schema, { source: { path: schemaPath, content: schemaContent } });
+  } catch (e) {
+    process.stderr.write(`error: schema compile failed: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  const r = v.validateJSON(data);
+  if (r.valid) { process.exit(0); }
+
+  const fmt = args.opts.format
+    || (args.opts.pretty ? 'pretty' : args.opts.compact ? 'compact' : null)
+    || (process.stdout.isTTY ? 'pretty' : 'compact');
+  const colorOpt = args.opts.color || (args.opts.noColor ? 'never' : 'auto');
+  const ctx = `${dataPath} against ${schemaPath}`;
+  let out;
+  if (fmt === 'json') {
+    out = renderJSON(r.errors, { pretty: true, context: ctx });
+  } else if (fmt === 'pretty') {
+    out = renderPretty(r.errors, { color: colorOpt, context: ctx, maxErrors: args.opts.maxErrors });
+  } else if (fmt === 'compact') {
+    out = renderCompact(r.errors, { color: colorOpt, context: ctx });
+  } else {
+    process.stderr.write(`error: --format must be pretty, compact, or json (got "${fmt}")\n`);
+    process.exit(2);
+  }
+  process.stderr.write(out + '\n');
+  process.exit(1);
+}
+
 function main() {
   const argv = process.argv.slice(2);
   if (argv.length === 0) { usage(); process.exit(0); }
@@ -237,6 +408,11 @@ function main() {
     return;
   }
 
+  if (cmd === 'validate') {
+    cmdValidate(args);
+    return;
+  }
+
   process.stderr.write(`error: unknown command "${cmd}"\n\n`);
   usage();
   process.exit(1);

package/build.d.ts

@@ -19,6 +19,12 @@ export interface BuildOptions {
   strict?: boolean;
   /** Emit a .d.mts/.d.cts/.d.ts sibling for each compiled module. Default: true. */
   types?: boolean;
+  /**
+   * Embed a schema source map and bake per-error `schemaSource` frames.
+   * Defaults to true when `NODE_ENV !== 'production'`, false otherwise.
+   * Set explicitly to override the environment default.
+   */
+  source?: boolean;
 }
 
 export interface CompiledEntry {

package/index.browser.mjs

@@ -1,4 +1,4 @@
 // Browser ESM entry — same code, native addon stubbed out by bundler via "browser" field.
 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/index.d.ts

@@ -12,6 +12,66 @@ export interface ValidationError {
   parentSchema?: object;
 }
 
+export interface SchemaSource {
+  file: string;
+  line: number;
+  col: number;
+  text: string;
+}
+
+export interface DataFrame {
+  byteOffset: number;
+  length: number;
+  line: number;
+  col: number;
+  text: string;
+}
+
+export interface Suggestion {
+  text: string;
+  kind: 'typo' | 'format' | 'coercion' | 'similar-key';
+}
+
+export type ErrorCode = `ATA${number}`;
+
+export interface RichValidationError {
+  code: ErrorCode;
+  message: string;
+  keyword: string;
+  path: string;
+  expected?: string;
+  received?: string;
+  schemaPath?: string;
+  schemaSource?: SchemaSource;
+  dataFrame?: DataFrame;
+  suggestion?: Suggestion;
+  docUrl?: string;
+  // Back-compat aliases retained indefinitely
+  instancePath?: string;
+  dataPath?: string;
+  params?: Record<string, unknown>;
+  parentSchema?: unknown;
+}
+
+export interface RenderOptions {
+  color?: 'auto' | 'always' | 'never';
+  cwd?: string;
+}
+
+export interface PrettyOptions extends RenderOptions {
+  maxErrors?: number;
+}
+
+export interface CompactOptions extends RenderOptions {}
+
+export interface JSONRenderOptions {
+  pretty?: boolean;
+}
+
+export function renderPretty(errors: RichValidationError[], opts?: PrettyOptions): string;
+export function renderCompact(errors: RichValidationError[], opts?: CompactOptions): string;
+export function renderJSON(errors: RichValidationError[], opts?: JSONRenderOptions): string;
+
 /** A user-supplied format checker. Receives the candidate value, returns true if valid. */
 export type FormatChecker = (value: string) => boolean;
 
@@ -42,6 +102,17 @@ export interface ValidatorOptions {
    * instead of collecting full error details. Smaller hot-path allocation.
    */
   abortEarly?: boolean;
+  /**
+   * Optional source descriptor for the schema. When supplied, validation errors
+   * carry a `schemaSource` frame pointing to the originating file/line/col.
+   */
+  source?: { path: string; content: string };
+  /**
+   * When true (default), validate() returns enriched errors with stable codes,
+   * docUrl, expected/received hints. Set to false to opt back into the
+   * v0.14 error shape.
+   */
+  richErrors?: boolean;
 }
 
 export interface BundleStandaloneOptions extends ValidatorOptions {