@ata-project/unplugin 0.1.1 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Compiles JSON Schema files into self-contained [ata-validator](https://ata-validator.com) modules at build time, with TypeScript declarations, in Vite, Webpack, Rollup, Rolldown, esbuild and Rspack. One plugin, built on [unplugin](https://github.com/unjs/unplugin).
 
-The generated module imports nothing. A small schema compiles to about 1.4 KB gzipped and a ten-field one to about 4.8 KB, full error detail included; the module exports `validate`, `isValid` and the inferred type, and runs anywhere plain JavaScript runs.
+The generated module imports nothing. A small schema compiles to about 1.3 KB gzipped and a ten-field one to about 2.6 KB, full error detail included, on ata-validator 1.36.0; the module exports `validate`, `isValid` and the inferred type, and runs anywhere plain JavaScript runs.
 
 Schemas can be authored as `.json`, `.js` or `.ts`.
 
@@ -145,6 +145,60 @@ Other sources (`.json` without the `.schema` suffix, `.js`, `.ts`) produce
 | `nameFromFile` | file name in PascalCase | Type name for schemas without `title` or `$id`. |
 | `root` | from the bundler | Where the globs resolve from. Vite's root, Webpack's and Rspack's `context` and esbuild's `absWorkingDir` are read; Rollup and Rolldown need it passed. |
 | `alias` | Vite's `resolve.alias` | Import aliases inside `.ts` schema files. tsconfig `paths` work without configuration. |
+| `compileAway` | `false` | Replace `new Validator(schema)` in your code with a validator compiled at build time, where that gives the same results. See below. Needs ata-validator 1.36.0. |
+
+## compileAway: keep `new Validator`, drop the compiler
+
+With `compileAway: true`, code written against the runtime API is compiled at
+build time without being changed:
+
+```js
+import { Validator } from 'ata-validator'
+
+const check = new Validator({
+  type: 'object',
+  properties: { id: { type: 'integer', minimum: 1 }, name: { type: 'string', minLength: 1 } },
+  required: ['id', 'name'],
+})
+
+export const handle = (body) => check.validate(body)
+```
+
+The plugin puts a compiled validator in place of the `new Validator(...)` call,
+and once nothing else in the file uses the `ata-validator` import, the import
+goes with it, so the runtime compiler is not in the bundle. For the three-schema
+entry in `test/fixtures/compile-away`, one of them with defaults, a minified Vite
+library build is 115.7 KB gzipped without it and 15.5 KB with it, on
+ata-validator 1.36.0. Across the 977 schemas of SchemaStore, 725 can be compiled
+away this way.
+
+The replacement answers `validate()`, `isValidObject()`, `validateJSON()` and
+`isValidJSON()` as a `Validator` with default options does: the same verdicts,
+defaults filled in, `data` on success, and the same errors, enriched the same
+way, since they come from the same code in ata-validator. ata-validator's own
+tests hold that over every case of the official JSON Schema test suite and over
+seeded schemas with defaults at every depth.
+
+A call is replaced only when all of this is true, and left to the runtime
+otherwise:
+
+- `Validator` is a named import from `ata-validator`;
+- the schema argument is an object literal, a top-level `const` bound to one,
+  the default import of a relative `.json` file, or `defineSchema(...)` around
+  one of those;
+- there is no second argument, or it is `{ useDefaults: false }` (or
+  `{ useDefaults: true }`), written as a literal or a top-level `const`; that
+  one option needs ata-validator 1.37.0, and older versions keep such calls on
+  the runtime;
+- the result goes into a `const` that is not exported and is only used as
+  `name.validate(...)`, `name.isValidObject(...)`, `name.validateJSON(...)` or
+  `name.isValidJSON(...)`;
+- ata-validator can compile the schema to the same results. It declines custom
+  `errorMessage`s and shapes its code generator cannot express, which the
+  runtime answers with its interpreted engine.
+
+Any other option (`new Validator(schema, { coerceTypes: true })`), a schema
+built at run time, or an instance passed around stays as written.
 
 ## How it works
 
@@ -174,7 +228,10 @@ const { files, results } = await compile({ schemas: 'schemas/**/*.json', root: p
 ## Tests
 
 `npm test` compiles the same entry with Vite, Webpack, Rollup, Rolldown,
-esbuild and Rspack, imports each bundle and runs the validator it contains.
+esbuild and Rspack, imports each bundle and runs the validator it contains. The
+compileAway tests build a second entry with all six, check that neither the
+runtime compiler nor the interpreter is in the output, and compare every answer
+with `new Validator`; the decline rules are tested on their own.
 
 ## Package name
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ata-project/unplugin",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Compile JSON, JS and TS schema files to ata-validator standalone modules at build time, in Vite, Webpack, Rollup, Rolldown, esbuild and Rspack.",
   "type": "module",
   "main": "./src/index.js",
@@ -71,12 +71,14 @@
     "ata-validator": ">=1.0.0"
   },
   "dependencies": {
+    "@babel/parser": "^7.29.9",
     "jiti": "^2.7.0",
+    "magic-string": "^1.4.2",
     "unplugin": "^3.3.0"
   },
   "devDependencies": {
     "@rspack/core": "^1.7.0",
-    "ata-validator": "^1.25.0",
+    "ata-validator": "^1.37.0",
     "esbuild": "^0.28.0",
     "rolldown": "^1.2.8",
     "rollup": "^4.60.0",

package/src/compile-away.js

@@ -0,0 +1,284 @@
+// Compile-away: `new Validator(schema)` from ata-validator, with a schema the
+// build can read, becomes a validator compiled at build time, so the runtime
+// compiler stays out of the bundle. The source is left as the author wrote it;
+// only the emitted module changes.
+//
+// A call is replaced only when every one of these holds, and left alone
+// otherwise, so turning this on can cost a saving but not change behaviour:
+//   - `Validator` is a named import from 'ata-validator', declared once;
+//   - the call has exactly one argument, and that argument is a value the
+//     build can read without running code: an object literal, a top-level
+//     `const` bound to one, the default import of a relative `.json` file, or
+//     `defineSchema(...)` around any of those;
+//   - the result is assigned to a `const` declared once in the file, not
+//     exported, and every other use of that name calls validate(),
+//     isValidObject(), validateJSON() or isValidJSON() on it;
+//   - ata-validator's compiledModuleFor() returns a module for the schema. It
+//     declines schemas the replacement would not answer exactly as the runtime
+//     does (custom error messages, shapes its error generator cannot express),
+//     and ata's own test suite holds the rest to the runtime's results. The
+//     wrapper gets the schema as the runtime reads it, compiledSchemaFor(), so
+//     it fills defaults and orders errors the same way.
+// The compiled module is inlined as a function scope next to the imports; it
+// imports nothing, so no virtual module or extra file is involved.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { parse } from '@babel/parser'
+import MagicString from 'magic-string'
+
+const METHODS = new Set(['validate', 'isValidObject', 'validateJSON', 'isValidJSON'])
+const NOT_STATIC = Symbol('not static')
+
+// Keys that hold child nodes. Types are left out on purpose: they are erased
+// before anything runs, so a name used in a type annotation says nothing about
+// how the value is used.
+function children(node) {
+  const out = []
+  for (const key in node) {
+    if (key === '__parent' || key === 'loc' || key === 'start' || key === 'end' || key === 'extra' || key === 'leadingComments' || key === 'trailingComments' || key === 'innerComments') continue
+    if (key === 'typeAnnotation' || key === 'returnType' || key === 'typeParameters' || key === 'superTypeParameters' || key === 'implements') continue
+    const v = node[key]
+    if (Array.isArray(v)) { for (const c of v) if (c && typeof c.type === 'string') out.push([c, key]) }
+    else if (v && typeof v.type === 'string') out.push([v, key])
+  }
+  return out
+}
+
+function isTypeOnly(node) {
+  return node.type.startsWith('TS') && !['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TSTypeAssertion', 'TSParameterProperty'].includes(node.type)
+}
+
+// Every binding a pattern introduces.
+function bindingNames(pattern, out) {
+  if (!pattern) return out
+  switch (pattern.type) {
+    case 'Identifier': out.push(pattern.name); break
+    case 'ObjectPattern': for (const p of pattern.properties) bindingNames(p.type === 'RestElement' ? p.argument : p.value, out); break
+    case 'ArrayPattern': for (const e of pattern.elements) bindingNames(e, out); break
+    case 'AssignmentPattern': bindingNames(pattern.left, out); break
+    case 'RestElement': bindingNames(pattern.argument, out); break
+    case 'TSParameterProperty': bindingNames(pattern.parameter, out); break
+  }
+  return out
+}
+
+// One walk: how many times each name is declared anywhere in the file, and
+// every identifier in a value position together with its parent.
+function scan(ast) {
+  const declared = new Map()
+  const refs = []
+  const declare = (name) => declared.set(name, (declared.get(name) || 0) + 1)
+  const visit = (node, parent, key) => {
+    if (isTypeOnly(node)) return
+    switch (node.type) {
+      case 'VariableDeclarator': for (const n of bindingNames(node.id, [])) declare(n); break
+      case 'FunctionDeclaration': case 'FunctionExpression': case 'ArrowFunctionExpression': case 'ObjectMethod': case 'ClassMethod': case 'ClassPrivateMethod':
+        if (node.id && node.type !== 'FunctionExpression') declare(node.id.name)
+        if (node.type === 'FunctionExpression' && node.id) declare(node.id.name)
+        for (const p of node.params) for (const n of bindingNames(p, [])) declare(n)
+        break
+      case 'ClassDeclaration': case 'ClassExpression': if (node.id) declare(node.id.name); break
+      case 'ImportSpecifier': case 'ImportDefaultSpecifier': case 'ImportNamespaceSpecifier': declare(node.local.name); break
+      case 'CatchClause': for (const n of bindingNames(node.param, [])) declare(n); break
+      case 'Identifier': {
+        const binding = parent && ((parent.type === 'VariableDeclarator' && key === 'id') || (key === 'params') || ((parent.type === 'ImportSpecifier' || parent.type === 'ImportDefaultSpecifier' || parent.type === 'ImportNamespaceSpecifier')) || ((parent.type === 'FunctionDeclaration' || parent.type === 'FunctionExpression' || parent.type === 'ClassDeclaration' || parent.type === 'ClassExpression') && key === 'id'))
+        const propertyName = parent && (((parent.type === 'MemberExpression' || parent.type === 'OptionalMemberExpression') && key === 'property' && !parent.computed) || ((parent.type === 'ObjectProperty' || parent.type === 'ObjectMethod' || parent.type === 'ClassProperty' || parent.type === 'ClassMethod') && key === 'key' && !parent.computed && !parent.shorthand) || parent.type === 'LabeledStatement' || parent.type === 'BreakStatement' || parent.type === 'ContinueStatement' || (parent.type === 'ImportSpecifier' && key === 'imported') || (parent.type === 'ExportSpecifier' && key === 'exported'))
+        if (!binding && !propertyName) refs.push({ node, parent, key })
+        return
+      }
+    }
+    for (const [child, k] of children(node)) { child.__parent = node; visit(child, node, k) }
+  }
+  visit(ast.program, null, null)
+  return { declared, refs }
+}
+
+// The value an expression stands for, when reading it needs no code to run.
+function staticValue(node, ctx, seen = new Set()) {
+  switch (node.type) {
+    case 'TSAsExpression': case 'TSSatisfiesExpression': case 'TSNonNullExpression': case 'TSTypeAssertion': case 'ParenthesizedExpression':
+      return staticValue(node.expression, ctx, seen)
+    case 'StringLiteral': case 'NumericLiteral': case 'BooleanLiteral': return node.value
+    case 'NullLiteral': return null
+    case 'TemplateLiteral': return node.expressions.length === 0 ? node.quasis[0].value.cooked : NOT_STATIC
+    case 'UnaryExpression': return node.operator === '-' && node.argument.type === 'NumericLiteral' ? -node.argument.value : NOT_STATIC
+    case 'ArrayExpression': {
+      const out = []
+      for (const el of node.elements) {
+        if (!el || el.type === 'SpreadElement') return NOT_STATIC
+        const v = staticValue(el, ctx, seen)
+        if (v === NOT_STATIC) return NOT_STATIC
+        out.push(v)
+      }
+      return out
+    }
+    case 'ObjectExpression': {
+      const out = {}
+      for (const p of node.properties) {
+        if (p.type !== 'ObjectProperty' || p.computed) return NOT_STATIC
+        const k = p.key.type === 'Identifier' ? p.key.name : (p.key.type === 'StringLiteral' || p.key.type === 'NumericLiteral') ? String(p.key.value) : null
+        if (k === null || k === '__proto__') return NOT_STATIC
+        const v = staticValue(p.value, ctx, seen)
+        if (v === NOT_STATIC) return NOT_STATIC
+        out[k] = v
+      }
+      return out
+    }
+    case 'Identifier': {
+      if (seen.has(node.name) || ctx.declared.get(node.name) !== 1) return NOT_STATIC
+      const source = ctx.constants.get(node.name)
+      if (!source) return NOT_STATIC
+      seen.add(node.name)
+      const v = source.json !== undefined ? source.json() : staticValue(source.init, ctx, seen)
+      seen.delete(node.name)
+      return v
+    }
+    case 'CallExpression':
+      if (node.callee.type === 'Identifier' && node.callee.name === ctx.defineSchema && node.arguments.length === 1) return staticValue(node.arguments[0], ctx, seen)
+      return NOT_STATIC
+  }
+  return NOT_STATIC
+}
+
+// Top level `const NAME = <expr>` and `import NAME from './x.json'`.
+function constantsOf(ast, id) {
+  const constants = new Map()
+  for (const stmt of ast.program.body) {
+    const decl = stmt.type === 'ExportNamedDeclaration' ? stmt.declaration : stmt
+    if (decl && decl.type === 'VariableDeclaration' && decl.kind === 'const') {
+      for (const d of decl.declarations) if (d.id.type === 'Identifier' && d.init) constants.set(d.id.name, { init: d.init })
+    }
+    if (stmt.type === 'ImportDeclaration' && stmt.importKind !== 'type' && /^\.{1,2}\/.*\.json$/.test(stmt.source.value)) {
+      const def = stmt.specifiers.find((s) => s.type === 'ImportDefaultSpecifier')
+      if (def) {
+        const file = path.resolve(path.dirname(id), stmt.source.value)
+        constants.set(def.local.name, { json: () => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return NOT_STATIC } } })
+      }
+    }
+  }
+  return constants
+}
+
+// `const name = new Validator(...)`, declared once, not exported, and used only
+// as `name.<method>(...)` with a supported method.
+function replaceableBinding(newExpr, ctx) {
+  const decl = newExpr.__parent
+  if (!decl || decl.type !== 'VariableDeclarator' || decl.init !== newExpr || decl.id.type !== 'Identifier') return null
+  const list = decl.__parent
+  if (!list || list.type !== 'VariableDeclaration' || list.kind !== 'const') return null
+  if (list.__parent && list.__parent.type === 'ExportNamedDeclaration') return null
+  const name = decl.id.name
+  if (ctx.declared.get(name) !== 1) return null
+  for (const r of ctx.refs) {
+    if (r.node.name !== name) continue
+    const p = r.parent
+    const member = p && (p.type === 'MemberExpression' || p.type === 'OptionalMemberExpression') && r.key === 'object' && !p.computed && p.property.type === 'Identifier' && METHODS.has(p.property.name)
+    const called = member && p.__parent && (p.__parent.type === 'CallExpression' || p.__parent.type === 'OptionalCallExpression') && p.__parent.callee === p
+    if (!called) return null
+  }
+  return name
+}
+
+function inlineModule(src, index) {
+  const body = src.split('\n').filter((l) => !/^export\s/.test(l)).join('\n')
+  return `const __ataCompiled${index} = (() => {\n${body}\nreturn { validate, isValid };\n})();\n`
+}
+
+// The options of `new Validator(schema, options)` as a third argument for
+// fromCompiled(), or NOT_STATIC when the call has to stay on the runtime: options
+// that are not a literal the build can read, or that name anything this
+// ata-validator's wrapper does not reproduce. `useDefaults: true` is the default
+// and needs no argument.
+function compiledOptionsArg(node, ctx, supported) {
+  const opts = staticValue(node, ctx)
+  if (opts === NOT_STATIC || opts === null || typeof opts !== 'object' || Array.isArray(opts)) return NOT_STATIC
+  for (const [key, value] of Object.entries(opts)) {
+    if (!supported.includes(key)) return NOT_STATIC
+    if (key === 'useDefaults' && typeof value !== 'boolean') return NOT_STATIC
+  }
+  return opts.useDefaults === false ? '{"useDefaults":false}' : ''
+}
+
+export function compileAway(code, id, ata) {
+  const { compiledModuleFor, compiledSchemaFor } = ata
+  const supportedOptions = Array.isArray(ata.compiledOptions) ? ata.compiledOptions : []
+  if (!code.includes('ata-validator')) return null
+  let ast
+  try {
+    ast = parse(code, { sourceType: 'module', plugins: ['typescript', 'jsx'], errorRecovery: false })
+  } catch {
+    return null
+  }
+  let validatorName = null
+  let importDecl = null
+  let defineSchema = null
+  let lastImportEnd = 0
+  for (const stmt of ast.program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue
+    lastImportEnd = Math.max(lastImportEnd, stmt.end)
+    if (stmt.source.value !== 'ata-validator' || stmt.importKind === 'type') continue
+    for (const s of stmt.specifiers) {
+      if (s.type !== 'ImportSpecifier' || s.importKind === 'type') continue
+      const imported = s.imported.type === 'Identifier' ? s.imported.name : s.imported.value
+      if (imported === 'Validator') { validatorName = s.local.name; importDecl = stmt }
+      if (imported === 'defineSchema') defineSchema = s.local.name
+    }
+  }
+  if (!validatorName) return null
+
+  const { declared, refs } = scan(ast)
+  if (declared.get(validatorName) !== 1) return null
+  const ctx = { declared, refs, constants: constantsOf(ast, id), defineSchema }
+
+  const s = new MagicString(code)
+  const modules = []
+  const done = new Set()
+  for (const r of refs) {
+    if (r.node.name !== validatorName) continue
+    const expr = r.parent
+    if (!expr || expr.type !== 'NewExpression' || r.key !== 'callee') continue
+    if (expr.arguments.length !== 1 && expr.arguments.length !== 2) continue
+    let optionsArg = ''
+    if (expr.arguments.length === 2) {
+      optionsArg = compiledOptionsArg(expr.arguments[1], ctx, supportedOptions)
+      if (optionsArg === NOT_STATIC) continue
+    }
+    if (!replaceableBinding(expr, ctx)) continue
+    const schema = staticValue(expr.arguments[0], ctx)
+    if (schema === NOT_STATIC || schema === null || typeof schema !== 'object' || Array.isArray(schema)) continue
+    let src = null
+    try { src = compiledModuleFor(schema, { format: 'esm' }) } catch { src = null }
+    if (!src) continue
+    const index = modules.length
+    modules.push(inlineModule(src, index))
+    s.overwrite(expr.start, expr.end, `__ataFromCompiled(__ataCompiled${index}, ${JSON.stringify(compiledSchemaFor(schema))}${optionsArg ? ', ' + optionsArg : ''})`)
+    done.add(expr)
+  }
+  if (done.size === 0) return null
+
+  // `Validator`, and `defineSchema` when it only wrapped a replaced schema,
+  // leave the import once nothing else uses them, and the import goes when it
+  // is left empty, so no bundler has to prove the runtime unused.
+  const inReplaced = (node) => { for (const e of done) if (node.start >= e.start && node.end <= e.end) return true; return false }
+  const unused = new Set()
+  for (const spec of importDecl.specifiers) {
+    if (spec.type !== 'ImportSpecifier') continue
+    const name = spec.local.name
+    if (name !== validatorName && name !== defineSchema) continue
+    if (ctx.declared.get(name) !== 1) continue
+    if (!refs.some((r) => r.node.name === name && !inReplaced(r.node))) unused.add(spec)
+  }
+  if (unused.size === importDecl.specifiers.length) s.remove(importDecl.start, importDecl.end)
+  else if (unused.size) {
+    const kept = importDecl.specifiers.filter((sp) => !unused.has(sp))
+    const text = (sp) => code.slice(sp.start, sp.end)
+    const def = kept.find((sp) => sp.type === 'ImportDefaultSpecifier')
+    const named = kept.filter((sp) => sp.type === 'ImportSpecifier')
+    const clause = [def ? text(def) : null, named.length ? `{ ${named.map(text).join(', ')} }` : null].filter(Boolean).join(', ')
+    s.overwrite(importDecl.start, importDecl.end, `import ${clause} from ${code.slice(importDecl.source.start, importDecl.source.end)}`)
+  }
+  s.prepend(`import { fromCompiled as __ataFromCompiled } from 'ata-validator/compiled';\n`)
+  s.appendLeft(lastImportEnd, '\n' + modules.join(''))
+  return { code: s.toString(), map: s.generateMap({ hires: true, source: id, includeContent: true }), replaced: done.size }
+}

package/src/core.js

@@ -41,6 +41,7 @@ const DEFAULT_OPTIONS = {
   format: 'esm',
   abortEarly: false,
   types: true,
+  compileAway: false,
   nameFromFile: (file) => {
     const base = path.basename(file, path.extname(file)).replace(/\.schema$/i, '')
     return pascal(base)
@@ -60,7 +61,18 @@ async function loadAta() {
       'unplugin-ata requires ata-validator >= 0.19.0 with the ata-validator/build entry.',
     )
   }
-  return { ...api, toStandaloneModule: build.toStandaloneModule }
+  // compiledModuleFor exists from ata-validator 1.35.0; compile-away needs it
+  // and is skipped with a warning when it is missing.
+  const canCompileAway = typeof build.compiledModuleFor === 'function' && typeof build.compiledSchemaFor === 'function'
+  return {
+    ...api,
+    toStandaloneModule: build.toStandaloneModule,
+    compiledModuleFor: canCompileAway ? build.compiledModuleFor : null,
+    compiledSchemaFor: canCompileAway ? build.compiledSchemaFor : null,
+    // The Validator options fromCompiled() reproduces, from ata-validator
+    // 1.37.0; before it, only calls without options are replaced.
+    compiledOptions: canCompileAway && Array.isArray(build.compiledOptions) ? build.compiledOptions : [],
+  }
 }
 
 function ensureArray(value) {
@@ -337,6 +349,10 @@ export function createSession(userOptions = {}) {
       )
       return { files, results }
     },
+    // ata-validator itself, loaded once for every hook that needs it.
+    api() {
+      return (apiPromise ??= loadAta())
+    },
     async compileIfMatching(file) {
       if (!file) return null
       const api = await (apiPromise ??= loadAta())

package/src/index.d.ts

@@ -21,6 +21,15 @@ export interface Options {
   root?: string
   /** Aliases for imports inside `.ts` schema files. Vite's `resolve.alias` is picked up. */
   alias?: Record<string, string>
+  /**
+   * Replace `new Validator(schema)` with a validator compiled at build time
+   * wherever the schema can be read without running code and the instance is
+   * only used through validate(), isValidObject(), validateJSON() and
+   * isValidJSON(), so the runtime compiler stays out of the bundle. Results are
+   * the ones the runtime gives. Needs ata-validator 1.35.0 or later.
+   * Default: `false`.
+   */
+  compileAway?: boolean
 }
 
 export interface CompileResult {

package/src/index.js

@@ -10,6 +10,9 @@
 import path from 'node:path'
 import { createUnplugin } from 'unplugin'
 import { createSession, normalizeAlias, compile, __internal } from './core.js'
+import { compileAway } from './compile-away.js'
+
+const SOURCE = /\.[cm]?[jt]sx?$/
 
 export const unpluginFactory = (userOptions = {}) => {
   const session = createSession(userOptions)
@@ -28,6 +31,29 @@ export const unpluginFactory = (userOptions = {}) => {
       await session.compileIfMatching(id)
     },
 
+    // compileAway: `new Validator(schema)` with a schema the build can read
+    // becomes a validator compiled here, and the runtime compiler leaves the
+    // bundle. See src/compile-away.js for what is replaced and what is not.
+    transformInclude(id) {
+      if (!userOptions.compileAway) return false
+      const file = id.split('?')[0]
+      return SOURCE.test(file) && !file.split(/[\\/]/).includes('node_modules')
+    },
+
+    async transform(code, id) {
+      if (!code.includes('ata-validator')) return null
+      const api = await session.api()
+      if (!api.compiledModuleFor) {
+        if (!session.warnedCompileAway) {
+          session.warnedCompileAway = true
+          session.logger?.warn?.('[unplugin-ata] compileAway needs ata-validator 1.36.0 or later; nothing was replaced')
+        }
+        return null
+      }
+      const out = compileAway(code, id.split('?')[0], api)
+      return out ? { code: out.code, map: out.map } : null
+    },
+
     // Where `schemas` globs resolve from. Vite says so in configResolved,
     // Webpack and Rspack in compiler.context, esbuild in absWorkingDir; Rollup
     // has no notion of a project root, so it takes the `root` option or the