ata-validator 1.20.0 → 1.21.0

package/index.js

@@ -2049,6 +2049,8 @@ const { toTypeScript } = require("./lib/ts-gen");
 const { renderPretty } = require("./lib/render-pretty");
 const { renderCompact } = require("./lib/render-compact");
 const { toOutput } = require("./lib/output-format");
+const { toRetryMessage } = require("./lib/retry-message");
+const { describeSchema } = require("./lib/describe-schema");
 const { renderJSON } = require("./lib/render-json");
 const { suggestFor } = require("./lib/suggestions");
 const { reprValue } = require("./lib/enrich-error");
@@ -2279,6 +2281,8 @@ module.exports = {
   renderPretty,
   renderCompact,
   toOutput,
+  toRetryMessage,
+  describeSchema,
   renderJSON,
   attachSuggestions, // internal: used by the renderers; not public API
 };

package/lib/describe-schema.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// Schema -> the description to put in a model's prompt.
+//
+// Everyone hand-writes a prose description of the shape they want and keeps it
+// next to a schema that enforces something slightly different. The two drift,
+// quietly, because nothing checks one against the other. This derives the
+// first from the second.
+//
+// It is not a style preference. Measured on one model, first attempt only, 30
+// documents, no retry:
+//
+//   nothing but the task                    0 of 30 valid
+//   a field list written by hand            0 of 30
+//   a careful description written by hand   0 of 30
+//   this                                   23 of 30
+//
+// The careful hand-written one failed on exactly two fields, in all 30 cases:
+// the two whose values are an internal vocabulary. A person writes "the
+// settlement status, uppercase with underscores" because a person describes
+// fields. Those values cannot be described, only listed, and a generator lists
+// them.
+//
+// Scope follows lib/ts-gen.js, which walks the same shapes: properties and
+// required, arrays, enum and const, oneOf/anyOf/allOf, and $ref into local
+// $defs. Anything else is described as `any` rather than guessed at.
+
+const MAX_DEPTH = 12;
+
+function lit (v) {
+  try { return JSON.stringify(v); } catch (_) { return String(v); }
+}
+
+function resolveRef (schema, defs) {
+  const m = typeof schema.$ref === 'string' && schema.$ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+  if (m && defs && defs[m[1]]) return defs[m[1]];
+  return null;
+}
+
+// The constraints worth stating to a model, in the order a reader wants them:
+// what it is, then which values, then how big.
+function constraintsOf (s) {
+  const out = [];
+  if (Array.isArray(s.enum)) out.push('one of ' + s.enum.map(lit).join(', '));
+  else if (s.const !== undefined) out.push('exactly ' + lit(s.const));
+  else if (s.type) out.push(Array.isArray(s.type) ? s.type.join(' or ') : s.type);
+
+  if (typeof s.format === 'string') out.push(s.format + ' format');
+  if (typeof s.pattern === 'string') out.push('matching ' + s.pattern);
+
+  const range = (min, max, unit) => {
+    if (min !== undefined && max !== undefined) out.push(`${min} to ${max}${unit}`);
+    else if (min !== undefined) out.push(`at least ${min}${unit}`);
+    else if (max !== undefined) out.push(`at most ${max}${unit}`);
+  };
+  range(s.minLength, s.maxLength, ' characters');
+  range(s.minimum, s.maximum, '');
+  range(s.minItems, s.maxItems, ' items');
+  if (s.exclusiveMinimum !== undefined) out.push('greater than ' + s.exclusiveMinimum);
+  if (s.exclusiveMaximum !== undefined) out.push('less than ' + s.exclusiveMaximum);
+  if (typeof s.multipleOf === 'number') out.push(multipleOfPhrase(s.multipleOf));
+  if (s.uniqueItems === true) out.push('all items different');
+  if (typeof s.description === 'string' && s.description) out.push(s.description);
+  return out;
+}
+
+// `multipleOf: 0.01` is how a schema says "money". A model acts on "rounded to
+// 2 decimal places" and does not reliably act on "a multiple of 0.01": in the
+// measurement behind this file, that one phrase was most of the gap between
+// this output and a careful description written by a person.
+function multipleOfPhrase (m) {
+  if (m > 0 && m < 1) {
+    const places = Math.round(Math.log10(1 / m));
+    if (Math.abs(Math.pow(10, -places) - m) < Number.EPSILON * 8) {
+      return `rounded to ${places} decimal place${places === 1 ? '' : 's'}`;
+    }
+  }
+  return 'a multiple of ' + m;
+}
+
+function isObjectSchema (s) {
+  return s && typeof s === 'object' && s.properties && typeof s.properties === 'object';
+}
+
+function describeObjectBody (schema, depth, defs, lines) {
+  const pad = '  '.repeat(depth);
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  for (const [key, sub] of Object.entries(schema.properties)) {
+    describeNode(sub, key + (required.has(key) ? '' : ' (optional)'), depth, defs, lines);
+  }
+  for (const key of required) {
+    if (!(key in schema.properties)) lines.push(`${pad}${key}: required, any`);
+  }
+  if (schema.additionalProperties === false) lines.push(`${pad}no other fields`);
+}
+
+function describeNode (schema, label, depth, defs, lines) {
+  const pad = '  '.repeat(depth);
+  if (schema === true || schema === undefined) { lines.push(`${pad}${label}: any`); return; }
+  if (schema === false) { lines.push(`${pad}${label}: nothing is allowed here`); return; }
+  if (typeof schema !== 'object' || schema === null || depth > MAX_DEPTH) {
+    lines.push(`${pad}${label}: any`);
+    return;
+  }
+
+  const target = schema.$ref ? resolveRef(schema, defs) : null;
+  if (target) { describeNode(target, label, depth, defs, lines); return; }
+
+  // allOf is the intersection, so its parts describe the same value.
+  if (Array.isArray(schema.allOf) && schema.allOf.length) {
+    const merged = Object.assign({}, schema);
+    delete merged.allOf;
+    for (const part of schema.allOf) {
+      const resolved = part && part.$ref ? resolveRef(part, defs) || part : part;
+      if (resolved && typeof resolved === 'object') Object.assign(merged, resolved, {
+        properties: Object.assign({}, merged.properties, resolved.properties),
+        required: [].concat(merged.required || [], resolved.required || []),
+      });
+    }
+    if (!merged.properties) delete merged.properties;
+    if (!merged.required || !merged.required.length) delete merged.required;
+    describeNode(merged, label, depth, defs, lines);
+    return;
+  }
+
+  const alternatives = schema.oneOf || schema.anyOf;
+  if (Array.isArray(alternatives) && alternatives.length) {
+    lines.push(`${pad}${label}: one of the following shapes`);
+    alternatives.forEach((alt, i) => describeNode(alt, `option ${i + 1}`, depth + 1, defs, lines));
+    return;
+  }
+
+  if (isObjectSchema(schema)) {
+    const own = constraintsOf(schema).filter((c) => c !== 'object');
+    lines.push(`${pad}${label}: object${own.length ? ` (${own.join(', ')})` : ''}`);
+    describeObjectBody(schema, depth + 1, defs, lines);
+    return;
+  }
+
+  const rawItems = schema.items;
+  if (schema.type === 'array' && rawItems && typeof rawItems === 'object') {
+    const items = rawItems.$ref ? resolveRef(rawItems, defs) || rawItems : rawItems;
+    const own = constraintsOf(schema).filter((c) => c !== 'array');
+    const bounds = own.length ? ` (${own.join(', ')})` : '';
+    // An item that is itself an object gets its fields listed underneath. One
+    // that is a scalar reads better on the same line than as a nested entry
+    // called "item".
+    if (isObjectSchema(items)) {
+      lines.push(`${pad}${label}: array${bounds}, each item is an object:`);
+      describeObjectBody(items, depth + 1, defs, lines);
+      return;
+    }
+    if (items.oneOf || items.anyOf || items.allOf) {
+      lines.push(`${pad}${label}: array${bounds}, each item is:`);
+      describeNode(items, 'item', depth + 1, defs, lines);
+      return;
+    }
+    const inner = constraintsOf(items).join(', ') || 'any';
+    lines.push(`${pad}${label}: array${bounds} of ${inner}`);
+    return;
+  }
+
+  lines.push(`${pad}${label}: ${constraintsOf(schema).join(', ') || 'any'}`);
+}
+
+// describeSchema(schema, opts) -> string
+//   opts.name  what to call the top level (default 'output')
+function describeSchema (schema, opts) {
+  const name = (opts && opts.name) || 'output';
+  const defs = (schema && (schema.$defs || schema.definitions)) || null;
+  const lines = [];
+  describeNode(schema, name, 0, defs, lines);
+  return lines.join('\n');
+}
+
+module.exports = { describeSchema };

package/lib/retry-message.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// The string to send back to a model when its structured output failed
+// validation.
+//
+// This exists because of a measurement rather than a preference. Feeding the
+// conventional error text back into a retry loop, one model, an invoice schema,
+// paired so the same failing output went to both arms:
+//
+//   constraints the model could infer from context   40 of 40 recovered
+//   constraints it could not (an internal vocabulary) 0 of 30 recovered
+//
+// With the expected values named in the message, the second case was 30 of 30.
+// The conventional message for `enum` is "must be equal to one of the allowed
+// values", which names neither the values nor what arrived, so the model
+// guesses. It guesses plausibly and it is always wrong: "HH" for a Hamburg
+// office, "FR" for a Lyon desk. Every retry came back well formed and still
+// invalid, and no number of further retries can fix it, because what is needed
+// was never in the loop.
+//
+// ata already carries the missing halves on each error, `detail` and
+// `received`. The trap is that joining `message`, which is the obvious thing to
+// do, throws both away. So this is one call that does not.
+
+function line (error) {
+  const where = error.instancePath || error.path || '';
+  const body = typeof error.detail === 'string' && error.detail ? error.detail : error.message;
+  // `detail` usually quotes the offending value already; saying it twice reads
+  // like a stutter in a string that is going into a prompt. A container is
+  // summarised as `[object, ~0.1KB]` rather than shown, which tells a model
+  // nothing it cannot see in its own output, so that is left out too.
+  const raw = error.received === undefined || error.received === null ? '' : String(error.received);
+  const useless = raw.charAt(0) === '[' && /^\[(object|array)\b/.test(raw);
+  const received = useless ? '' : raw;
+  const got = received && body && !body.includes(received) ? `, got ${received}` : '';
+  return `${where || '/'}: ${body}${got}`;
+}
+
+// toRetryMessage(errors, opts)
+//   opts.limit  most errors to include (default 20). A model does not act on
+//               forty complaints, and the prompt is not free.
+function toRetryMessage (errors, opts) {
+  if (!errors || typeof errors.length !== 'number' || errors.length === 0) return '';
+  const limit = opts && typeof opts.limit === 'number' ? opts.limit : 20;
+  const shown = errors.length > limit ? Array.prototype.slice.call(errors, 0, limit) : errors;
+  const lines = [];
+  for (let i = 0; i < shown.length; i++) lines.push(line(shown[i]));
+  if (errors.length > shown.length) lines.push(`and ${errors.length - shown.length} more`);
+  return lines.join('\n');
+}
+
+module.exports = { toRetryMessage };

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.20.0",
+  "version": "1.21.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",
@@ -51,7 +51,7 @@
     "release:check": "node scripts/regen-safe-regex-source.js && node tests/test_pack_purity.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
     "build": "cmake-js build --target ata",
     "rebuild": "cmake-js rebuild --target ata",
-    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_buffer_reject_cost.js && node tests/test_nan_verdict.js && node tests/test_remove_additional_nested.js && node tests/test_exclusive_bounds.js && node tests/test_engine_differential.js && node tests/test_error_shape_differential.js && node tests/test_output_format.js && node tests/test_aot_parse.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.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_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_formats_single_pass.js && node tests/test_format_single_error.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_hybrid_agreement.js && node tests/test_codegen_edge_shapes.js && node tests/test_ajv_errors.js && node tests/test_custom_keywords.js && node tests/test_aot_external_checks.js && node tests/test_ajv_parity.js && node tests/test_user_format_error_path.js && node tests/test_unevaluated_error_path.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_error_order_ordinal.js && node tests/test_rejection_shape.js && node tests/test_lazy_normalization.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_schema_scan.js && node tests/test_lazy_errors.js && node tests/test_lazy_instance.js && node tests/test_cyclic_input.js && node tests/test_native_error_codes.js && node tests/test_verdict_preprocess.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.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_additive_fields.js && node tests/test_diagnostic_source.js && node tests/test_diagnose.js && node tests/test_correlate.js && node tests/test_diagnostics_score.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 tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_buffer_reject_cost.js && node tests/test_nan_verdict.js && node tests/test_remove_additional_nested.js && node tests/test_exclusive_bounds.js && node tests/test_engine_differential.js && node tests/test_error_shape_differential.js && node tests/test_output_format.js && node tests/test_retry_message.js && node tests/test_describe_schema.js && node tests/test_aot_parse.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.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_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_formats_single_pass.js && node tests/test_format_single_error.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_hybrid_agreement.js && node tests/test_codegen_edge_shapes.js && node tests/test_ajv_errors.js && node tests/test_custom_keywords.js && node tests/test_aot_external_checks.js && node tests/test_ajv_parity.js && node tests/test_user_format_error_path.js && node tests/test_unevaluated_error_path.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_error_order_ordinal.js && node tests/test_rejection_shape.js && node tests/test_lazy_normalization.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_schema_scan.js && node tests/test_lazy_errors.js && node tests/test_lazy_instance.js && node tests/test_cyclic_input.js && node tests/test_native_error_codes.js && node tests/test_verdict_preprocess.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.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_additive_fields.js && node tests/test_diagnostic_source.js && node tests/test_diagnose.js && node tests/test_correlate.js && node tests/test_diagnostics_score.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 tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js && node tests/run_suite.js draft7 && node tests/run_suite.js v1",
     "test:compat": "node tests/test_compat.js",
@@ -122,13 +122,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.20.0",
-    "@ata-validator/native-darwin-x64": "1.20.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.20.0",
-    "@ata-validator/native-linux-arm64-musl": "1.20.0",
-    "@ata-validator/native-linux-x64-gnu": "1.20.0",
-    "@ata-validator/native-linux-x64-musl": "1.20.0",
-    "@ata-validator/native-win32-x64": "1.20.0"
+    "@ata-validator/native-darwin-arm64": "1.21.0",
+    "@ata-validator/native-darwin-x64": "1.21.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.21.0",
+    "@ata-validator/native-linux-arm64-musl": "1.21.0",
+    "@ata-validator/native-linux-x64-gnu": "1.21.0",
+    "@ata-validator/native-linux-x64-musl": "1.21.0",
+    "@ata-validator/native-win32-x64": "1.21.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"