ata-validator 1.61.2 → 1.61.3

package/README.md

@@ -1,6 +1,6 @@
 # ata-validator
 
-JSON Schema validation that compiles for speed and still runs where code generation is blocked. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, draft 7 and the [JSON Schema v1 dialect](#dialects). First-class TypeScript inference, and `ata build` emits a standalone module that imports nothing.
+JSON Schema validation where the TypeScript type comes from the schema, or the schema from the type. Write the schema once and `validate` narrows to it; write the type once and the bundler plugin writes its schema in at build time. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, 2019-09, drafts 7, 6 and 4 and the [JSON Schema v1 dialect](#dialects), and `ata build` emits a standalone module that imports nothing, with its `.d.mts` beside it.
 
 [![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)
@@ -10,6 +10,60 @@ JSON Schema validation that compiles for speed and still runs where code generat
 
 1.0 is a stability commitment: see [docs/STABILITY.md](docs/STABILITY.md) for the semver, deprecation, and error-code guarantees.
 
+## The type and the schema
+
+One source of truth, in either direction. A schema written with `defineSchema` carries its
+type: `validate` narrows `data` to it, and `Infer` pulls the type out for a signature.
+
+```ts
+import { defineSchema, Validator, type Infer } from 'ata-validator'
+
+const User = defineSchema({
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    email: { type: 'string', format: 'email' },
+    role: { enum: ['admin', 'user'] },
+  },
+  required: ['id', 'email'],
+})
+
+const users = new Validator(User)
+const r = users.validate(JSON.parse(body))
+if (r.valid) {
+  r.data.id    // number
+  r.data.role  // 'admin' | 'user' | undefined
+  r.data.name  // a type error: the schema has no name
+}
+
+type User = Infer<typeof User>
+```
+
+Or start from the type. `schemaOf<T>()` has no run-time form; the bundler plugin reads `T`
+with the TypeScript checker and writes its JSON Schema in place of the call, with the JSDoc
+tags carrying what a type cannot say, and the `new Validator(...)` then compiles away like any
+static schema.
+
+```ts
+import { Validator, schemaOf } from 'ata-validator'
+
+interface Account {
+  /** @minimum 1 */
+  id: number
+  /** @format email */
+  email: string
+  role?: 'admin' | 'user'
+}
+
+const accounts = new Validator(schemaOf<Account>())
+```
+
+`ata build` writes a `.d.mts` next to every compiled module, with the inferred type and an
+`isValid` predicate on it, so a module that imports nothing still narrows. The chainable
+builder in `ata-validator/t`, `Infer` on `anyOf`, `allOf`, tuples and recursive `$ref`, and
+the async `t.refine` are in [Type-safe schemas](#type-safe-schemas); the plugin's type reading
+is in [its README](https://github.com/ata-core/unplugin-ata#a-schema-from-a-typescript-type-schemaofuser).
+
 ## Who uses ata
 
 Projects whose code depends on ata, from GitHub's dependency graph, a framework that lists its
@@ -399,31 +453,7 @@ v.countValid(ndjson);        // number
 
 ### Type-safe schemas
 
-ata infers TypeScript types straight from plain JSON Schema. Write the schema once with `defineSchema`, and both runtime validation and the static type come from it, with no builder DSL and no second type declaration to keep in sync.
-
-```ts
-import { defineSchema, Validator } from 'ata-validator'
-
-const userSchema = defineSchema({
-  type: 'object',
-  properties: {
-    id: { type: 'integer', minimum: 1 },
-    role: { type: 'string', enum: ['admin', 'user'] },
-  },
-  required: ['id'],
-})
-
-const v = new Validator(userSchema)
-const result = v.validate(data)
-if (result.valid) {
-  result.data.id   // number
-  result.data.role // 'admin' | 'user' | undefined
-} else {
-  // result.errors: ValidationError[]
-}
-```
-
-`defineSchema` returns the schema untouched at runtime; in TypeScript it gives keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed. `new Validator(schema)` carries the inferred type, so a successful `validate` narrows `result.data` with no manual annotation.
+ata infers TypeScript types straight from plain JSON Schema, as in [the opening example](#the-type-and-the-schema): `defineSchema` returns the schema untouched at runtime and, in TypeScript, gives keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed. `new Validator(schema)` carries the inferred type, so a successful `validate` narrows `result.data` with no manual annotation.
 
 #### Extracting the type: `Infer`
 
@@ -671,7 +701,11 @@ validator only ever called (`v.validate(x)`, `v.isValidObject(x)`), never handed
 it uses the bare wrappers of `ata-validator/compiled-bare` instead, which leave out Standard
 Schema and the extension hook nothing can reach there: 0.3 KB gzipped for both, and
 `ata-validator/compiled-bare-rich` for one that reads ata's own errors. The same form app
-bundles to 10.7 KB gzipped, or 3.1 KB with `richErrors: false` on the validator that reads errors. The errors
+bundles to 10.7 KB gzipped, or 3.1 KB with `richErrors: false` on the validator that reads errors.
+A validator handed only to a Standard Schema consumer the plugin knows (Hono's
+`sValidator`, `hono-openapi`, TanStack Form, oRPC, tRPC, Elysia) takes `ata-validator/compiled-standard`, which
+carries `~standard` alone on a module with plain errors: a Hono route on Cloudflare Workers goes
+from 21.0 to 12.2 KB gzipped, 4.4 KB over Hono by itself. The errors
 then carry `keyword`, `instancePath`, `schemaPath`, `params` and `message`, as that option has
 always given them, without `received`, `suggestion` or `docUrl`.
 
@@ -728,6 +762,37 @@ works as a CI step. This is the check that found the two silent divergences
 fixed in 1.59.0 and 1.60.0, now in a form a project can run on every change.
 It does not run the `.bun.ts` target, which needs Bun's compiler.
 
+### What a schema change does (`ata diff`)
+
+Reading two versions of a schema side by side says which keywords changed. It
+does not say which documents change verdict, and that is the question before
+a deploy: which requests that pass today get a 400 tomorrow. `ata diff` answers
+it with documents:
+
+```bash
+npx ata diff schemas/user.json schemas/user-v2.json --samples test/fixtures
+```
+
+```
+401 documents: 102 accepted by both, 293 rejected by both, 6 rejected only by user-v2.json, 0 accepted only by user-v2.json
+
+Rejected by user-v2.json, accepted by user.json (a client sending these gets a rejection after the change):
+  minimum@/age: 4 documents, 1 of them the project's own, must be >= 18
+    {"email":"kid@example.com","name":"Kid","age":15}  (test/fixtures/signup-teen.json)
+  maxLength@/name: 2 documents, must NOT have more than 40 characters
+    {"email":"a@b.co","name":"abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij...
+```
+
+The documents are the ones `ata verify` makes, from both schemas (200 each by
+default, half with one rule broken, then a value on either side of every
+bound), plus the project's own samples. Each one is checked by a `Validator`
+built from each schema, and the ones that change verdict are grouped by the
+rule that decides them, with one example each, the project's own document
+when there is one. The exit code is 1 when a document the old schema accepts
+is rejected by the new one, so a pull request that tightens a schema fails
+the check until someone looks. Generated documents are a sample, not a proof:
+a change this reports is real, one it does not report may still exist.
+
 ### Bun, compiled ahead of time
 
 Bun's ahead-of-time compiler (`bun build --compile --aot`, an open pull

package/bin/ata.js

@@ -15,6 +15,8 @@ Usage:
   ata migrate  [dir]         [options]  Report what switching from ajv would change; --write applies it.
   ata verify   <glob>...     [options]  Check that each schema's compiled module answers as the runtime
                                         does, on generated documents and the project's samples.
+  ata diff     <old> <new>   [options]  What a change to a schema does: the documents the old schema
+                                        accepts and the new one rejects, and the reverse, by rule.
 
 Verify options:
   --generate <n>          Documents made from each schema, half with one rule broken. Default: 200
@@ -23,6 +25,13 @@ Verify options:
   --json                  Report as JSON
   --out-dir, --suffix, --format    Where the modules are, as given to ata build
 
+Diff options:
+  --generate <n>          Documents made from each schema. Default: 200
+  --samples <path>        The project's own documents, checked too (repeatable)
+  --seed <n>              Seed for the generated documents. Default: 1
+  --json                  Report as JSON
+  Exit status 1 when a document the old schema accepts is rejected by the new one.
+
 Validate options:
   --pretty                Render errors with source frames (default on TTY)
   --compact               Render errors as one line each (default when piped)
@@ -487,6 +496,24 @@ function cmdVerify (args) {
   })().catch((e) => { process.stderr.write(`error: ${e.message}\n`); process.exit(1); });
 }
 
+function cmdDiff (args) {
+  if (args._.length < 2) {
+    process.stderr.write('error: ata diff <old-schema> <new-schema>\n');
+    process.exit(2);
+  }
+  const buildLib = require('../lib/aot-build');
+  const { diffSchemas, renderDiff, breaking } = require('../lib/schema-diff');
+  let oldSchema, newSchema;
+  try { oldSchema = buildLib.parseSchemaFile(args._[0]); newSchema = buildLib.parseSchemaFile(args._[1]); } catch (e) { process.stderr.write(`error: ${e.message}\n`); process.exit(2); }
+  const samples = args.opts.samples === undefined ? [] : [].concat(args.opts.samples);
+  let report;
+  try {
+    report = diffSchemas(oldSchema, newSchema, { generate: Number.isFinite(args.opts.generate) ? args.opts.generate : 200, seed: Number.isFinite(args.opts.seed) ? args.opts.seed : 1, samples });
+  } catch (e) { process.stderr.write(`error: ${e.message}\n`); process.exit(2); }
+  process.stdout.write(renderDiff(report, { json: !!args.opts.json, oldName: path.basename(args._[0]), newName: path.basename(args._[1]) }) + '\n');
+  process.exit(breaking(report) ? 1 : 0);
+}
+
 function cmdValidate (args) {
   if (args._.length < 2) {
     process.stderr.write('error: ata validate <schema> <data-file>\n');
@@ -592,6 +619,11 @@ function main() {
     return;
   }
 
+  if (cmd === 'diff') {
+    cmdDiff(args);
+    return;
+  }
+
   if (cmd === 'migrate') {
     const { migrate, formatReport } = require('../lib/migrate');
     const result = migrate(args._[0] || '.', { write: !!args.opts.write });

package/compiled-standard.d.ts

@@ -0,0 +1,6 @@
+// ata-validator/compiled-standard: the compiled-module wrapper for a validator
+// a bundler plugin sees handed to Standard Schema consumers only.
+import type { StandardSchemaV1Props } from './index.js';
+import type { CompiledModule } from './compiled.js';
+
+export function bareStandard<T = unknown>(mod: CompiledModule, schema: object | boolean, useDefaults?: boolean): { '~standard': StandardSchemaV1Props<T> };

package/compiled-standard.mjs

@@ -0,0 +1,66 @@
+// ata-validator/compiled-standard as an ES module of its own, not a re-export
+// of the CommonJS file, so a bundler adds no interop code (see
+// compiled-bare.mjs). The same `~standard` as lib/compiled-standard.js builds
+// through lib/standard-schema.js; tests/test_compiled_standard.js holds the
+// two to the same issues and the same schema documents.
+
+// When the module's error function answers valid where its verdict said no,
+// the disagreement is reported rather than turned into an acceptance.
+const DISAGREES = [{ message: 'schema validation failed', instancePath: '' }];
+const EMPTY_PATH = Object.freeze([]);
+
+// A JSON pointer as a Standard Schema path: an all-digit segment without a
+// leading zero is an array index and comes out as a number.
+function pathOf(pointer) {
+  if (!pointer) return EMPTY_PATH;
+  const out = [];
+  for (const raw of pointer.split('/').slice(1)) {
+    const seg = raw.indexOf('~') >= 0 ? raw.replace(/~1/g, '/').replace(/~0/g, '~') : raw;
+    out.push({ key: /^(?:0|[1-9][0-9]*)$/.test(seg) ? Number(seg) : seg });
+  }
+  return Object.freeze(out);
+}
+
+// Standard JSON Schema: the document, as a copy, for its own dialect.
+function jsonSchemaOf(schema) {
+  const convert = (options) => {
+    const target = options && options.target;
+    if (schema === true) return {};
+    if (schema === false) return { not: {} };
+    const declared = typeof schema.$schema === 'string' ? schema.$schema : '';
+    const dialect = declared === '' || declared.includes('draft/2020-12/schema') ? 'draft-2020-12'
+      : declared.includes('draft-07/schema') ? 'draft-07' : declared;
+    if (target !== dialect) {
+      throw new TypeError(`ata-validator cannot provide a ${dialect} schema as ${String(target)}; it does not convert between dialects`);
+    }
+    return JSON.parse(JSON.stringify(schema));
+  };
+  return Object.freeze({ input: convert, output: convert });
+}
+
+export function bareStandard(mod, schema, useDefaults) {
+  const fill = useDefaults !== false && typeof mod.applyDefaults === 'function' ? mod.applyDefaults : null;
+  const isValid = mod.isValid;
+  const errFn = mod.validate;
+  return {
+    '~standard': Object.freeze({
+      version: 1,
+      vendor: 'ata-validator',
+      jsonSchema: jsonSchemaOf(schema),
+      validate(value) {
+        if (fill !== null) fill(value);
+        if (isValid(value)) return { value };
+        const r = errFn(value);
+        const errors = r && r.valid === false ? r.errors : DISAGREES;
+        const issues = new Array(errors.length);
+        for (let i = 0; i < errors.length; i++) {
+          const e = errors[i];
+          issues[i] = { message: e.message || 'validation failed', path: pathOf(e.instancePath != null ? e.instancePath : (e.path || '')) };
+        }
+        return { issues };
+      },
+    }),
+  };
+}
+
+export default { bareStandard };

package/lib/compiled-standard.js

@@ -0,0 +1,33 @@
+'use strict';
+
+// bareStandard: the compiled-module wrapper for a validator that is only ever
+// handed to a Standard Schema consumer (a router's validator middleware, a
+// form library, an RPC layer) and never called by its own code. Such a
+// consumer reads `~standard` and nothing else, and an issue carries a message
+// and a path, so the wrapper is built on a module written with
+// `plainErrors: true`, whose errors are those two things in schema order, and
+// carries no error pipeline, no Standard Schema install and no extension hook.
+// The issues are the runtime's (tests/test_compiled_standard.js). A bundler
+// plugin puts this in place of `new Validator(schema)` where it sees that use.
+
+const { standardSchemaFor } = require('./standard-schema');
+
+const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+// When the module's error function answers valid where its verdict said no,
+// the disagreement is reported rather than turned into an acceptance.
+const VERDICT_DISAGREES = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ keyword: 'validation', instancePath: '', schemaPath: '#', params: Object.freeze({}), message: 'schema validation failed' })]) });
+
+function bareStandard(mod, schema, useDefaults) {
+  const fill = useDefaults !== false && typeof mod.applyDefaults === 'function' ? mod.applyDefaults : null;
+  const isValid = mod.isValid;
+  const errFn = mod.validate;
+  const validate = (data) => {
+    if (fill !== null) fill(data);
+    if (isValid(data)) return VALID;
+    const r = errFn(data);
+    return r && r.valid === false ? r : VERDICT_DISAGREES;
+  };
+  return { '~standard': standardSchemaFor(null, () => schema, (_, value) => validate(value)) };
+}
+
+module.exports = { bareStandard };

package/lib/schema-diff.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// What a change to a schema does to documents: which ones the old schema
+// accepted and the new one rejects (a client sending what used to pass gets a
+// 400), and which ones the new one accepts and the old one did not (a rule
+// was loosened). Reading two schemas side by side tells you which keywords
+// changed; it does not tell you which documents change verdict, and that is
+// the question before a deploy. The documents come from `generate` in
+// lib/verify.js, made from both schemas, half of them with one rule broken,
+// plus the values on either side of every bound, plus the project's own
+// samples. Generated documents are a sample, not a proof: a change this
+// finds is real, one it does not find may still exist.
+
+const { Validator } = require('../index.js');
+const { generate, readSamples } = require('./verify');
+
+const clone = (v) => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+const errorKey = (e) => `${e.keyword || ''}@${e.instancePath || ''}`;
+const first = (errors) => (errors && errors.length ? errors[0] : { keyword: 'validation', instancePath: '', message: 'validation failed' });
+
+// `samples`: paths of JSON or JSON Lines files, or directories of them.
+function diffSchemas (oldSchema, newSchema, { generate: count = 200, seed = 1, samples = [] } = {}) {
+  const before = new Validator(oldSchema);
+  const after = new Validator(newSchema);
+  const docs = [];
+  const seen = new Set();
+  const add = (doc, source) => {
+    if (doc === undefined) return;
+    const key = JSON.stringify(doc);
+    if (seen.has(key)) return;
+    seen.add(key);
+    docs.push({ doc, source });
+  };
+  for (const d of generate(oldSchema, count, seed, (x) => before.isValidObject(clone(x)))) add(d, 'generated from the old schema');
+  for (const d of generate(newSchema, count, seed + 1, (x) => after.isValidObject(clone(x)))) add(d, 'generated from the new schema');
+  for (const s of readSamples(samples)) if (!s.bad) add(s.doc, s.source);
+
+  const nowRejected = [];
+  const nowAccepted = [];
+  let bothAccept = 0;
+  let bothReject = 0;
+  for (const { doc, source } of docs) {
+    const a = before.validate(clone(doc));
+    const b = after.validate(clone(doc));
+    if (a.valid && b.valid) bothAccept++;
+    else if (!a.valid && !b.valid) bothReject++;
+    else if (a.valid) nowRejected.push({ doc, source, error: first(b.errors) });
+    else nowAccepted.push({ doc, source, error: first(a.errors) });
+  }
+  return {
+    documents: docs.length,
+    bothAccept,
+    bothReject,
+    nowRejected: grouped(nowRejected),
+    nowAccepted: grouped(nowAccepted),
+  };
+}
+
+// The documents of one kind, grouped by the rule that decides them (the
+// first error's keyword and place), each group with one example: one of the
+// project's own documents when the group holds one, since that is a document
+// somebody actually sends, else the first generated one.
+const generated = (source) => source.startsWith('generated');
+function grouped (list) {
+  const groups = new Map();
+  for (const item of list) {
+    const key = errorKey(item.error);
+    let g = groups.get(key);
+    if (g === undefined) groups.set(key, (g = { rule: key, message: item.error.message, count: 0, samples: 0, example: item.doc, source: item.source }));
+    g.count++;
+    if (!generated(item.source)) { g.samples++; if (generated(g.source)) { g.example = item.doc; g.source = item.source; } }
+  }
+  return { count: list.length, rules: [...groups.values()].sort((x, y) => y.count - x.count) };
+}
+
+function breaking (report) { return report.nowRejected.count > 0; }
+
+function renderDiff (report, { json = false, oldName = 'old', newName = 'new' } = {}) {
+  if (json) return JSON.stringify(report, null, 2);
+  const lines = [];
+  const show = (doc) => { const s = JSON.stringify(doc); return s.length > 120 ? s.slice(0, 117) + '...' : s; };
+  lines.push(`${report.documents} documents: ${report.bothAccept} accepted by both, ${report.bothReject} rejected by both, ${report.nowRejected.count} rejected only by ${newName}, ${report.nowAccepted.count} accepted only by ${newName}`);
+  if (report.nowRejected.count) {
+    lines.push('');
+    lines.push(`Rejected by ${newName}, accepted by ${oldName} (a client sending these gets a rejection after the change):`);
+    for (const g of report.nowRejected.rules) {
+      lines.push(`  ${g.rule}: ${g.count} ${g.count === 1 ? 'document' : 'documents'}${g.samples ? `, ${g.samples} of them the project's own` : ''}, ${g.message}`);
+      lines.push(`    ${show(g.example)}${generated(g.source) ? '' : `  (${g.source})`}`);
+    }
+  }
+  if (report.nowAccepted.count) {
+    lines.push('');
+    lines.push(`Accepted by ${newName}, rejected by ${oldName} (what ${oldName} refused with):`);
+    for (const g of report.nowAccepted.rules) {
+      lines.push(`  ${g.rule}: ${g.count} ${g.count === 1 ? 'document' : 'documents'}${g.samples ? `, ${g.samples} of them the project's own` : ''}, ${g.message}`);
+      lines.push(`    ${show(g.example)}${generated(g.source) ? '' : `  (${g.source})`}`);
+    }
+  }
+  if (!report.nowRejected.count && !report.nowAccepted.count) lines.push('No document changed verdict.');
+  return lines.join('\n');
+}
+
+module.exports = { diffSchemas, renderDiff, breaking };

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.61.2';
+module.exports = '1.61.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.61.2",
+  "version": "1.61.3",
   "description": "JSON Schema validator that compiles to plain JavaScript, still runs where code generation is blocked, and can be compiled away at build time. Passes the full official test suite.",
   "type": "commonjs",
   "main": "index.js",
@@ -84,6 +84,11 @@
       "types": "./compiled-bare-rich.d.ts",
       "default": "./lib/compiled-bare-rich.js"
     },
+    "./compiled-standard": {
+      "types": "./compiled-standard.d.ts",
+      "import": "./compiled-standard.mjs",
+      "default": "./lib/compiled-standard.js"
+    },
     "./lite": {
       "types": "./lite.d.ts",
       "import": "./lite.mjs",
@@ -217,6 +222,8 @@
     "compiled-bare.mjs",
     "compiled-bare.d.ts",
     "compiled-bare-rich.d.ts",
+    "compiled-standard.mjs",
+    "compiled-standard.d.ts",
     "lite.js",
     "lite.mjs",
     "lite.d.ts",
@@ -231,13 +238,13 @@
     "codegen.d.ts"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.61.2",
-    "@ata-validator/native-darwin-x64": "1.61.2",
-    "@ata-validator/native-linux-arm64-gnu": "1.61.2",
-    "@ata-validator/native-linux-arm64-musl": "1.61.2",
-    "@ata-validator/native-linux-x64-gnu": "1.61.2",
-    "@ata-validator/native-linux-x64-musl": "1.61.2",
-    "@ata-validator/native-win32-x64": "1.61.2"
+    "@ata-validator/native-darwin-arm64": "1.61.3",
+    "@ata-validator/native-darwin-x64": "1.61.3",
+    "@ata-validator/native-linux-arm64-gnu": "1.61.3",
+    "@ata-validator/native-linux-arm64-musl": "1.61.3",
+    "@ata-validator/native-linux-x64-gnu": "1.61.3",
+    "@ata-validator/native-linux-x64-musl": "1.61.3",
+    "@ata-validator/native-win32-x64": "1.61.3"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"