ata-validator 0.15.0 → 0.15.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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

package/index.js

@@ -363,6 +363,19 @@ function buildSchemaMap(schemas) {
   return map
 }
 
+// Compile-cache key for a root schema plus its external schemas. Must include
+// the external schema CONTENT, not just their $ids: two validators can share a
+// root schema string and the same $id while pointing that $id at different
+// schemas (separate app instances, test suites, multi-tenant). Keying on $id
+// alone reuses the wrong compiled validator and silently mis-validates.
+function compileCacheKey(schemaStr, schemaMap) {
+  if (!schemaMap || schemaMap.size === 0) return schemaStr
+  const parts = []
+  for (const [id, s] of schemaMap) parts.push(id + '=' + JSON.stringify(s))
+  parts.sort()
+  return schemaStr + '\0' + parts.join('\0')
+}
+
 // Resolve a relative URI ref against a base URI
 function resolveRelativeRef(ref, baseId) {
   if (!baseId || ref.includes('://') || ref.startsWith('#')) return ref
@@ -371,6 +384,66 @@ function resolveRelativeRef(ref, baseId) {
   return baseId.substring(0, lastSlash + 1) + ref
 }
 
+// Resolve a cross-schema $ref to its target schema for preprocessing purposes.
+// Handles whole-schema refs (`shared#`), relative-id matching, and JSON pointer
+// fragments (`shared#/properties/id`). Returns null for local-only refs or when
+// the target cannot be found. Used only to read `type`/`properties` for
+// coercion/defaults/removeAdditional, never for validation.
+function resolveRefForPreprocess(ref, schemaMap) {
+  if (!schemaMap || schemaMap.size === 0 || typeof ref !== 'string') return null
+  const hashIdx = ref.indexOf('#')
+  const baseId = hashIdx >= 0 ? ref.slice(0, hashIdx) : ref
+  const fragment = hashIdx >= 0 ? ref.slice(hashIdx + 1) : ''
+  if (!baseId) return null
+  let base = null
+  if (schemaMap.has(baseId)) base = schemaMap.get(baseId)
+  else if (!ref.includes('://')) {
+    for (const [id, s] of schemaMap) {
+      if (id.endsWith('/' + baseId)) { base = s; break }
+    }
+  }
+  if (!base) return null
+  if (!fragment) return base
+  let target = base
+  for (const part of fragment.split('/')) {
+    if (part === '') continue
+    if (target == null || typeof target !== 'object') return null
+    target = target[part.replace(/~1/g, '/').replace(/~0/g, '~')]
+  }
+  return target == null ? null : target
+}
+
+// Preprocessing (coerce/defaults/removeAdditional) reads `schema.properties` and
+// each property's `type`. When the data shape lives behind a cross-schema $ref
+// (a whole-schema ref like Fastify's `params: { $ref: 'shared#' }`, or a
+// property ref like `{ id: { $ref: 'shared#/properties/id' } }`), follow the
+// ref so the preprocessor can see the referenced shape. Returns the schema with
+// such refs resolved, cloning only when a substitution is made.
+function resolveSchemaForPreprocess(schema, schemaMap) {
+  if (!schema || typeof schema !== 'object' || !schemaMap || schemaMap.size === 0) return schema
+  let s = schema
+  // Whole-schema ref (only when it has no own properties, to avoid dropping
+  // sibling keywords on schemas that mix $ref with properties).
+  if (s.$ref && !s.properties) {
+    const t = resolveRefForPreprocess(s.$ref, schemaMap)
+    if (t && typeof t === 'object') s = t
+  }
+  if (!s.properties) return s
+  // Property-level refs: substitute the resolved target so coercion sees `type`.
+  let cloned = null
+  for (const key of Object.keys(s.properties)) {
+    const p = s.properties[key]
+    if (p && typeof p === 'object' && p.$ref && !p.type) {
+      const t = resolveRefForPreprocess(p.$ref, schemaMap)
+      if (t && typeof t === 'object') {
+        if (!cloned) { cloned = Object.assign({}, s); cloned.properties = Object.assign({}, s.properties) }
+        cloned.properties[key] = t
+      }
+    }
+  }
+  return cloned || s
+}
+
 class Validator {
   constructor(schema, opts) {
     const options = opts || {};
@@ -531,9 +604,7 @@ class Validator {
 
     // Check cache first -- reuse compiled functions for same schema
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
-    const mapKey = this._schemaMap.size > 0
-      ? this._schemaStr + '\0' + [...this._schemaMap.keys()].sort().join('\0')
-      : this._schemaStr;
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
     // Custom formats are JS functions: bypass the compile cache since they can
     // differ between validators that share the same schema string.
     const cached = this._userFormats ? null : _compileCache.get(mapKey);
@@ -559,13 +630,17 @@ class Validator {
     }
     this._jsFn = jsFn;
 
-    // Data mutators -- try codegen first (12x faster), fallback to closure arrays
-    let preprocess = buildPreprocessCodegen(schemaObj, options);
+    // Data mutators -- try codegen first (12x faster), fallback to closure arrays.
+    // Follow cross-refs so coercion/defaults/removeAdditional see the referenced
+    // shape (e.g. Fastify `params: { $ref: 'shared#' }` or property refs like
+    // `{ id: { $ref: 'shared#/properties/id' } }`).
+    const preprocessSchema = resolveSchemaForPreprocess(schemaObj, this._schemaMap);
+    let preprocess = buildPreprocessCodegen(preprocessSchema, options);
     if (!preprocess) {
-      const applyDefaults = buildDefaultsApplier(schemaObj);
-      const applyCoerce = options.coerceTypes ? buildCoercer(schemaObj) : null;
+      const applyDefaults = buildDefaultsApplier(preprocessSchema);
+      const applyCoerce = options.coerceTypes ? buildCoercer(preprocessSchema) : null;
       const applyRemove = options.removeAdditional
-        ? buildRemover(schemaObj)
+        ? buildRemover(preprocessSchema)
         : null;
       const mutators = [applyRemove, applyCoerce, applyDefaults].filter(Boolean);
       preprocess =
@@ -1007,9 +1082,7 @@ class Validator {
     if (typeof process !== 'undefined' && process.env && process.env.ATA_FORCE_NAPI) return;
     if (!this._schemaStr) this._schemaStr = JSON.stringify(this._schemaObj);
     const sm = this._schemaMap.size > 0 ? this._schemaMap : null;
-    const mapKey = this._schemaMap.size > 0
-      ? this._schemaStr + '\0' + [...this._schemaMap.keys()].sort().join('\0')
-      : this._schemaStr;
+    const mapKey = compileCacheKey(this._schemaStr, this._schemaMap);
     // Custom formats are JS functions: skip the shared cache so different
     // validators with the same schema string but different formats don't collide.
     const cached = this._userFormats ? null : _compileCache.get(mapKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "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",

package/scripts/check-doc-coverage.js

@@ -10,7 +10,7 @@ const doc = fs.readFileSync(path.join(__dirname, '..', 'docs', 'error-codes.md')
 const missing = [];
 const placeholder = [];
 for (const code of all()) {
-  const headingRe = new RegExp(`^### ${code} `, 'm');
+  const headingRe = new RegExp(`^### ${code}\\b`, 'm');
   if (!headingRe.test(doc)) {
     missing.push(code);
     continue;