@jxsuite/schema 3.0.0 → 4.0.0

package/src/project-schemas.ts

@@ -23,20 +23,39 @@ import {
   PROJECT_FIELDS_SCHEMA_ID,
   documentPathsCoreMembers,
 } from "../defs/field-schema.schema";
+import type { JsonObject, JsonPrimitive, JsonValue } from "../types";
+import { isJsonObject, isString } from "./guards";
 
 export { DOCUMENT_PATHS_SCHEMA_ID, PROJECT_FIELDS_SCHEMA_ID } from "../defs/field-schema.schema";
 
+/**
+ * JSON as the schema builders write it. The `defs/*.schema.ts` fragments are `as const` literals,
+ * readonly all the way down, and a readonly array is not a `JsonValue[]`. Every {@link JsonValue}
+ * is also one of these, so a function that only reads or clones a schema accepts this type.
+ */
+export type ReadonlyJsonValue = JsonPrimitive | readonly ReadonlyJsonValue[] | ReadonlyJsonObject;
+
+/** The object member of {@link ReadonlyJsonValue}. */
+export interface ReadonlyJsonObject {
+  readonly [key: string]: ReadonlyJsonValue;
+}
+
 /** The canonical $id of the core project fragment. */
 export const PROJECT_CORE_SCHEMA_ID = "https://jxsuite.com/schema/project/core/v2";
 
+/**
+ * The conventional project-relative ref to the core project fragment: where `jx schema` points a
+ * project's entry document at the core it composes over when `@jxsuite/schema` is installed in the
+ * project's own `node_modules`.
+ */
+export const CONVENTIONAL_PROJECT_CORE_REF =
+  "./node_modules/@jxsuite/schema/schemas/project.core.schema.json";
+
 export const GENERATED_SCHEMA_COMMENT =
   "Generated by `jx schema` from project.json#/extensions — do not edit.";
 
 export interface ProjectSchemaInputs {
-  /**
-   * Project-relative path of the core fragment, e.g.
-   * "./node_modules/@jxsuite/schema/schemas/project.core.schema.json".
-   */
+  /** Project-relative path of the core fragment, e.g. {@link CONVENTIONAL_PROJECT_CORE_REF}. */
   corePath: string;
   /** Project-relative extension fragment paths, in extension declaration order. */
   fragments: string[];
@@ -49,7 +68,7 @@ export interface ProjectSchemaInputs {
 }
 
 /** Emit the `project.schema.json` entry document for a project. */
-export function emitProjectSchema(inputs: ProjectSchemaInputs): Record<string, unknown> {
+export function emitProjectSchema(inputs: ProjectSchemaInputs): JsonObject {
   const { corePath, fragments, fieldSchemaRefs = [] } = inputs;
   return {
     $comment: GENERATED_SCHEMA_COMMENT,
@@ -73,7 +92,7 @@ export function emitProjectSchema(inputs: ProjectSchemaInputs): Record<string, u
 // ─── Generic bundler (specs/extensions.md §5.4) ──────────────────────────────
 
 /** Injected JSON loader for {@link bundleSchema} — receives a normalized, slash-separated path. */
-export type SchemaJsonLoader = (path: string) => Promise<Record<string, unknown>>;
+export type SchemaJsonLoader = (path: string) => Promise<JsonObject>;
 
 /**
  * Bundle an entry document into a single self-contained compound schema for hosts that cannot fetch
@@ -84,22 +103,23 @@ export type SchemaJsonLoader = (path: string) => Promise<Record<string, unknown>
  * their `$id`s, refs inside an embedded absolute-`$id` resource are canonical and stay untouched,
  * and a resource whose `$id` is already present in the compound document is not embedded twice.
  *
- * @param {Record<string, unknown>} entry - The entry document (e.g. a parsed project.schema.json)
+ * @param {ReadonlyJsonObject} entry - The entry document (e.g. a parsed project.schema.json)
  * @param {SchemaJsonLoader} loadJson - Loader for `$ref` target files (host-restricted)
  * @param {string} baseDir - Directory the entry document's relative refs resolve against
  * @param {string[]} [alsoEmbed] - Relative paths of resources to embed even though no path-`$ref`
  *   reaches them, because they are referenced only by canonical `$id` (a document fragment whose
  *   `$defs` feed the paths union). Without this they would stay dangling.
- * @returns {Promise<Record<string, unknown>>} A new, self-contained schema (the input is not
- *   mutated)
+ * @returns {Promise<JsonObject>} A new, self-contained schema (the input is not mutated)
  */
 export async function bundleSchema(
-  entry: Record<string, unknown>,
+  entry: ReadonlyJsonObject,
   loadJson: SchemaJsonLoader,
   baseDir: string,
   alsoEmbed: string[] = [],
-): Promise<Record<string, unknown>> {
-  const bundled = structuredClone(entry);
+): Promise<JsonObject> {
+  /* SAFETY: structuredClone returns a fresh deep copy of pure JSON, so the input's readonly-ness
+     protects nothing here: no other reference to this copy exists while it is rewritten. */
+  const bundled = structuredClone(entry) as JsonObject;
   const embeddedByPath = new Map<string, string>();
   const embeddedIds = new Set<string>();
   collectResourceIds(bundled, embeddedIds);
@@ -112,7 +132,7 @@ export async function bundleSchema(
     if (prior !== undefined) {
       return prior;
     }
-    let resource: Record<string, unknown>;
+    let resource: JsonObject;
     try {
       resource = structuredClone(await loadJson(normalized));
     } catch (error) {
@@ -121,8 +141,7 @@ export async function bundleSchema(
         { cause: error },
       );
     }
-    const ownId =
-      typeof resource.$id === "string" && hasUriScheme(resource.$id) ? resource.$id : null;
+    const ownId = isString(resource.$id) && hasUriScheme(resource.$id) ? resource.$id : null;
     generatedCount += ownId === null ? 1 : 0;
     const id = ownId ?? `urn:jx:bundled:${generatedCount}`;
     embeddedByPath.set(normalized, id);
@@ -133,7 +152,12 @@ export async function bundleSchema(
     embeddedIds.add(id);
     resource.$id = id;
     await rewrite(resource, schemaDirOf(normalized), true);
-    const defs = (bundled.$defs ??= {}) as Record<string, unknown>;
+    /*
+     * SAFETY: JSON Schema 2020-12 §8.2.4 requires `$defs` to be an object, and every entry handed
+     * here is an emitted entry document (emitProjectSchema / emitDocumentSchema, or the committed
+     * file one of them wrote), whose `$defs` is always an object literal; absent, it becomes one.
+     */
+    const defs = (bundled.$defs ??= {}) as JsonObject;
     defs[id] = resource;
     return id;
   };
@@ -142,25 +166,29 @@ export async function bundleSchema(
    * Walk a (sub)schema rewriting relative-path `$ref`s. `fileDir` is the directory relative refs
    * resolve against, or null inside an embedded absolute-`$id` resource (canonical scope).
    */
-  const rewrite = async (node: unknown, fileDir: string | null, isRoot = false): Promise<void> => {
+  const rewrite = async (
+    node: JsonValue,
+    fileDir: string | null,
+    isRoot = false,
+  ): Promise<void> => {
     if (Array.isArray(node)) {
       for (const item of node) {
         await rewrite(item, fileDir);
       }
       return;
     }
-    if (node === null || typeof node !== "object") {
+    if (!isJsonObject(node)) {
       return;
     }
-    const obj = node as Record<string, unknown>;
+    const obj = node;
     let scope = fileDir;
-    if (!isRoot && typeof obj.$id === "string" && hasUriScheme(obj.$id)) {
+    if (!isRoot && isString(obj.$id) && hasUriScheme(obj.$id)) {
       // Entering an embedded resource with a canonical $id: refs inside resolve against that
       // $id (never the file location), so there is nothing to inline.
       scope = null;
     }
     const ref = obj.$ref;
-    if (typeof ref === "string" && scope !== null && !ref.startsWith("#") && !hasUriScheme(ref)) {
+    if (isString(ref) && scope !== null && !ref.startsWith("#") && !hasUriScheme(ref)) {
       const hashIndex = ref.indexOf("#");
       const target = hashIndex === -1 ? ref : ref.slice(0, hashIndex);
       const fragment = hashIndex === -1 ? "" : ref.slice(hashIndex);
@@ -217,11 +245,6 @@ const MAP_SUBSCHEMA_KEYWORDS = [
 /** Keywords whose value is an array of subschemas. */
 const LIST_SUBSCHEMA_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
 
-/** True for a plain object node (a candidate subschema); booleans and arrays are not. */
-function isSchemaObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Escape a `$defs` key for use as a JSON Pointer segment (RFC 6901). */
 function escapePointerSegment(segment: string): string {
   return segment.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -230,33 +253,32 @@ function escapePointerSegment(segment: string): string {
 /**
  * Walk the known subschema keyword positions of `node`.
  *
- * @param {Record<string, unknown>} node - The schema object to walk
+ * Only plain objects count as subschemas there; a boolean schema has nothing to walk.
+ *
+ * @param {JsonObject} node - The schema object to walk
  * @param {string} pointer - JSON Pointer of `node` within the document
- * @yields {[Record<string, unknown>, string]} Each subschema paired with its own JSON Pointer
+ * @yields {[JsonObject, string]} Each subschema paired with its own JSON Pointer
  */
-function* subschemaEntries(
-  node: Record<string, unknown>,
-  pointer: string,
-): Generator<[Record<string, unknown>, string]> {
+function* subschemaEntries(node: JsonObject, pointer: string): Generator<[JsonObject, string]> {
   for (const keyword of SINGLE_SUBSCHEMA_KEYWORDS) {
     const value = node[keyword];
     if (Array.isArray(value)) {
       for (const [index, item] of value.entries()) {
-        if (isSchemaObject(item)) {
+        if (isJsonObject(item)) {
           yield [item, `${pointer}/${keyword}/${index}`];
         }
       }
-    } else if (isSchemaObject(value)) {
+    } else if (isJsonObject(value)) {
       yield [value, `${pointer}/${keyword}`];
     }
   }
   for (const keyword of MAP_SUBSCHEMA_KEYWORDS) {
     const value = node[keyword];
-    if (!isSchemaObject(value)) {
+    if (!isJsonObject(value)) {
       continue;
     }
     for (const [name, item] of Object.entries(value)) {
-      if (isSchemaObject(item)) {
+      if (isJsonObject(item)) {
         yield [item, `${pointer}/${keyword}/${escapePointerSegment(name)}`];
       }
     }
@@ -267,7 +289,7 @@ function* subschemaEntries(
       continue;
     }
     for (const [index, item] of value.entries()) {
-      if (isSchemaObject(item)) {
+      if (isJsonObject(item)) {
         yield [item, `${pointer}/${keyword}/${index}`];
       }
     }
@@ -322,19 +344,20 @@ function slugForSchemaId(id: string, used: Set<string>): string {
  * `$id` shadowing (§5.3) still decides the outcome; it is simply resolved AT FLATTEN TIME, since
  * refs to a shadowed `$id` rewrite to the pointer of the entry document's embed.
  *
- * @param {Record<string, unknown>} entry - A bundled compound document (output of
- *   {@link bundleSchema})
- * @returns {Record<string, unknown>} A new single-resource schema (the input is not mutated)
+ * @param {ReadonlyJsonObject} entry - A bundled compound document (output of {@link bundleSchema})
+ * @returns {JsonObject} A new single-resource schema (the input is not mutated)
  */
-export function flattenSchema(entry: Record<string, unknown>): Record<string, unknown> {
-  const flat = structuredClone(entry);
+export function flattenSchema(entry: ReadonlyJsonObject): JsonObject {
+  /* SAFETY: structuredClone returns a fresh deep copy of pure JSON, so the input's readonly-ness
+     protects nothing here: no other reference to this copy exists while it is rewritten. */
+  const flat = structuredClone(entry) as JsonObject;
 
   // 1. Rekey URI-keyed `$defs` entries to readable slugs (pointers address them by key).
-  if (isSchemaObject(flat.$defs)) {
+  if (isJsonObject(flat.$defs)) {
     const used = new Set(Object.keys(flat.$defs).filter((key) => !hasUriScheme(key)));
-    const renamed: Record<string, unknown> = {};
+    const renamed: JsonObject = {};
     for (const [key, value] of Object.entries(flat.$defs)) {
-      const id = isSchemaObject(value) && typeof value.$id === "string" ? value.$id : key;
+      const id = isJsonObject(value) && isString(value.$id) ? value.$id : key;
       renamed[hasUriScheme(key) ? slugForSchemaId(id, used) : key] = value;
     }
     flat.$defs = renamed;
@@ -342,9 +365,9 @@ export function flattenSchema(entry: Record<string, unknown>): Record<string, un
 
   // 2. Map each embedded resource's `$id` to its pointer here (first wins, as the bundler embeds).
   const idToPointer = new Map<string, string>();
-  const scan = (node: Record<string, unknown>, pointer: string): void => {
+  const scan = (node: JsonObject, pointer: string): void => {
     const { $id } = node;
-    if (typeof $id === "string" && hasUriScheme($id) && !idToPointer.has($id)) {
+    if (isString($id) && hasUriScheme($id) && !idToPointer.has($id)) {
       idToPointer.set($id, pointer);
     }
     for (const [child, childPointer] of subschemaEntries(node, pointer)) {
@@ -354,10 +377,10 @@ export function flattenSchema(entry: Record<string, unknown>): Record<string, un
   scan(flat, "#");
 
   // 3. Rewrite refs against the enclosing resource, then dissolve the resource boundary.
-  const rewrite = (node: Record<string, unknown>, scope: string): void => {
+  const rewrite = (node: JsonObject, scope: string): void => {
     let inner = scope;
     const { $id } = node;
-    if (typeof $id === "string" && hasUriScheme($id)) {
+    if (isString($id) && hasUriScheme($id)) {
       inner = idToPointer.get($id) ?? scope;
       if (inner !== "#") {
         // The root keeps its identity; nested resources must not remain ref targets.
@@ -365,7 +388,7 @@ export function flattenSchema(entry: Record<string, unknown>): Record<string, un
       }
     }
     const ref = node.$ref;
-    if (typeof ref === "string") {
+    if (isString(ref)) {
       const hashIndex = ref.indexOf("#");
       const target = hashIndex === -1 ? ref : ref.slice(0, hashIndex);
       const fragment = hashIndex === -1 ? "" : ref.slice(hashIndex + 1);
@@ -390,18 +413,18 @@ export function flattenSchema(entry: Record<string, unknown>): Record<string, un
 }
 
 /** Collect every absolute `$id` already present in a document (embeds like the field union). */
-function collectResourceIds(node: unknown, out: Set<string>): void {
+function collectResourceIds(node: JsonValue, out: Set<string>): void {
   if (Array.isArray(node)) {
     for (const item of node) {
       collectResourceIds(item, out);
     }
     return;
   }
-  if (node === null || typeof node !== "object") {
+  if (!isJsonObject(node)) {
     return;
   }
-  const obj = node as Record<string, unknown>;
-  if (typeof obj.$id === "string" && hasUriScheme(obj.$id)) {
+  const obj = node;
+  if (isString(obj.$id) && hasUriScheme(obj.$id)) {
     out.add(obj.$id);
   }
   for (const value of Object.values(obj)) {
@@ -445,8 +468,8 @@ function schemaDirOf(path: string): string {
   return index === 0 ? "/" : path.slice(0, index);
 }
 
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function errorText(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
 }
 
 export interface DocumentSchemaInputs {
@@ -469,9 +492,9 @@ export interface DocumentSchemaInputs {
  * pointer stops resolving. Wrapping in `allOf` keeps the merge target off the root.
  *
  * @param {DocumentSchemaInputs} inputs - Core path and the contributed paths-union refs
- * @returns {Record<string, unknown>}
+ * @returns {ReadonlyJsonObject} Readonly because it shares the core members' `as const` objects
  */
-export function emitDocumentSchema(inputs: DocumentSchemaInputs): Record<string, unknown> {
+export function emitDocumentSchema(inputs: DocumentSchemaInputs): ReadonlyJsonObject {
   const { corePath, pathsValueRefs } = inputs;
   return {
     $comment: GENERATED_SCHEMA_COMMENT,
@@ -516,6 +539,12 @@ export interface ComposeProjectSchemasInputs {
   baseDir: string;
 }
 
+/** A project's two composed entry documents, as {@link composeProjectSchemas} returns them. */
+export interface ComposedProjectSchemas {
+  project: JsonObject;
+  document: JsonObject;
+}
+
 /**
  * Compose a project's two committed entry documents from the core schemas and its enabled
  * extensions' fragments — bundled, then flattened to root JSON pointers (§5.2/§5.4).
@@ -526,13 +555,12 @@ export interface ComposeProjectSchemasInputs {
  * — a project's schemas must not depend on which host generated them.
  *
  * @param {ComposeProjectSchemasInputs} inputs - Core refs, extension fragments, loader, base
- * @returns {Promise<{ project: Record<string, unknown>; document: Record<string, unknown> }>} The
- *   self-contained entry documents, ready to write or to hand an editor
+ * @returns {Promise<ComposedProjectSchemas>} The self-contained entry documents, ready to write or
+ *   to hand an editor
  */
-export async function composeProjectSchemas(inputs: ComposeProjectSchemasInputs): Promise<{
-  project: Record<string, unknown>;
-  document: Record<string, unknown>;
-}> {
+export async function composeProjectSchemas(
+  inputs: ComposeProjectSchemasInputs,
+): Promise<ComposedProjectSchemas> {
   const { baseDir, coreDocumentRef, coreProjectRef, extensions, loadJson } = inputs;
 
   const fragments: string[] = [];
@@ -594,14 +622,14 @@ async function fragmentDefsRefs(
   loadJson: SchemaJsonLoader,
   baseDir: string,
 ): Promise<string[]> {
-  let fragment: { $id?: unknown; $defs?: Record<string, unknown> };
+  let fragment: JsonObject;
   try {
     fragment = await loadJson(normalizeSchemaPath(`${normalizeSchemaPath(baseDir)}/${ref}`));
   } catch {
     return [];
   }
   const { $id } = fragment;
-  if (typeof $id !== "string" || !fragment.$defs) {
+  if (!isString($id) || !fragment.$defs) {
     return [];
   }
   return Object.keys(fragment.$defs).map((name) => `${$id}#/$defs/${name}`);

package/src/schema.ts

@@ -1,28 +1,34 @@
 /**
  * Jx-schema.ts — Jx JSON Schema 2020-12 meta-schema generator
- * @version 2.0.0
- * @license MIT
  *
- * Generates comprehensive JSON Schema 2020-12 documents that validate Jx source files.
- * Individual schema definitions live in ../defs/ as the single source of truth.
- * This module composes them and injects web standards data derived at generation time from:
+ * Generates comprehensive JSON Schema 2020-12 documents that validate Jx source files. Individual
+ * schema definitions live in ../defs/ as the single source of truth. This module composes them and
+ * injects web standards data derived at generation time from:
  *
- *   webref/elements — HTML element tag names
- *   webref/css      — CSS property names (camelCase CSSOM)
- *   webref/idl      — DOM EventHandler attribute names
+ * - `webref/elements`: HTML element tag names
+ * - `webref/css`: CSS property names (camelCase CSSOM)
+ * - `webref/idl`: DOM EventHandler attribute names
  *
  * Usage:
- *   import { generateSchema } from './schema.js';
- *   const schema = await generateSchema();
- *   fs.writeFileSync('schema.json', JSON.stringify(schema, null, 2));
+ *
+ * ```ts
+ * import { generateSchema } from "./schema.js";
+ * const schema = await generateSchema();
+ * fs.writeFileSync("schema.json", JSON.stringify(schema, null, 2));
+ * ```
  *
  * CLI:
- *   bun run schema.ts [output-path]
+ *
+ * ```sh
+ * bun run schema.ts [output-path]
+ * ```
  *
  * @module jx-schema
+ * @license MIT
+ * @version 2.0.0
  */
 
-import { listAll as listElements } from "@webref/elements";
+import { listAll } from "@webref/elements";
 import css from "@webref/css";
 import idl from "@webref/idl";
 
@@ -110,6 +116,8 @@ import {
 } from "../defs/field-schema.schema";
 import { imageConfigSchema } from "../defs/image-config.schema";
 import { projectConfigSchema } from "../defs/project-config.schema";
+import type { JsonObject, JsonValue } from "../types";
+import type { ReadonlyJsonObject } from "./project-schemas";
 
 // ─── Web standards data loader ────────────────────────────────────────────────
 
@@ -132,7 +140,7 @@ function loadWebData() {
 
 async function computeWebData() {
   const [elementsData, cssData, idlData] = await Promise.all([
-    listElements(),
+    listAll(),
     css.listAll(),
     idl.parseAll(),
   ]);
@@ -168,8 +176,7 @@ async function computeWebData() {
         if (
           member.type === "attribute" &&
           member.name?.startsWith("on") &&
-          typeof member.idlType?.idlType === "string" &&
-          member.idlType.idlType === "EventHandler"
+          member.idlType?.idlType === "EventHandler"
         ) {
           handlerSet.add(member.name);
         }
@@ -183,8 +190,8 @@ async function computeWebData() {
 
 // ─── Injection helpers ─────────────────────────────────────────────────────────
 
-function buildEventHandlerProperties(eventHandlers: string[]) {
-  const properties: Record<string, unknown> = {};
+function buildEventHandlerProperties(eventHandlers: string[]): JsonObject {
+  const properties: JsonObject = {};
   for (const name of eventHandlers) {
     properties[name] = {
       description: `Event handler for the "${name.slice(2)}" event.`,
@@ -198,11 +205,11 @@ function buildEventHandlerProperties(eventHandlers: string[]) {
   return properties;
 }
 
-function buildCssProperties(cssProps: string[]) {
+function buildCssProperties(cssProps: string[]): JsonObject {
   /* The authored `properties` come first so a `$`-prefixed metadata key survives: this function
      REPLACES the block's properties rather than adding to them, so anything the hand-written schema
      declared there was silently dropped — which is how `$description` validated as a number. */
-  const properties: Record<string, unknown> = { ...styleObjectSchema.properties };
+  const properties: JsonObject = { ...styleObjectSchema.properties };
   for (const name of cssProps) {
     /* A `{ $ref }` is a reactive VALUE, which the runtime has always resolved (spec.md §9.6) and
        only the validator refused: `style: { fontFamily: { $ref: "$map/item/face" } }` reported
@@ -718,11 +725,11 @@ export async function generateSchemaString() {
 // Minimal structural types for the optional `ajv` / `ajv-formats` peer deps
 // (no direct dependency, and shipping no types usable from here).
 interface AjvValidateFn {
-  (doc: unknown): boolean;
+  (doc: JsonValue): boolean;
   errors?: unknown[] | null;
 }
 interface AjvInstance {
-  compile: (schema: unknown) => AjvValidateFn;
+  compile: (schema: ReadonlyJsonObject) => AjvValidateFn;
 }
 type AjvCtor = new (opts: {
   allErrors: boolean;
@@ -736,20 +743,24 @@ type AddFormatsFn = (ajv: AjvInstance) => void;
  * document.schema.json from `jx schema`). The schema must be self-contained — external refs are not
  * resolved here.
  *
- * @param {Record<string, unknown>} doc - The document to validate
- * @param {Record<string, unknown>} schema - A self-contained 2020-12 schema
+ * @param {JsonValue} doc - The document to validate
+ * @param {ReadonlyJsonObject} schema - A self-contained 2020-12 schema
  * @returns {Promise<{ errors: unknown[] | null; valid: boolean }>}
  */
-export async function validateWithSchema(
-  doc: Record<string, unknown>,
-  schema: Record<string, unknown>,
-) {
+export async function validateWithSchema(doc: JsonValue, schema: ReadonlyJsonObject) {
   let Ajv: AjvCtor;
   let addFormats: AddFormatsFn;
   try {
-    // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
-    // (the default `ajv` export is draft-07 and can't compile a 2020-12 schema).
+    /*
+     * The generated schema is JSON Schema 2020-12, so use the matching Ajv build (the default
+     * `ajv` export is draft-07 and can't compile a 2020-12 schema).
+     * SAFETY: the default export of `ajv/dist/2020` is the Ajv2020 class. AjvCtor restates, in
+     * JSON terms, only the three constructor options, `compile` and the validate function's call
+     * and `errors` used below; ajv reports a schema value it cannot use as a thrown error.
+     */
     ({ default: Ajv } = (await import("ajv/dist/2020")) as { default: AjvCtor });
+    /* SAFETY: ajv-formats' default export is `addFormats(ajv, options?)`, which only registers
+       format validators on the instance it is given; this call passes the Ajv2020 built above. */
     // @ts-expect-error — optional peer dependency
     ({ default: addFormats } = (await import("ajv-formats")) as { default: AddFormatsFn });
   } catch {
@@ -765,22 +776,22 @@ export async function validateWithSchema(
   return { errors: validate.errors ?? null, valid };
 }
 
-export async function validateDocument(doc: Record<string, unknown>) {
-  return validateWithSchema(doc, (await generateSchema()) as Record<string, unknown>);
+export async function validateDocument(doc: JsonValue) {
+  return validateWithSchema(doc, await generateSchema());
 }
 
 /** Validate a .class.json class definition against the generated class schema. */
-export async function validateClass(doc: Record<string, unknown>) {
-  return validateWithSchema(doc, generateClassSchema() as Record<string, unknown>);
+export async function validateClass(doc: JsonValue) {
+  return validateWithSchema(doc, generateClassSchema());
 }
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
-async function runSchemaCli() {
+async function runSchemaCli(scriptPath: string) {
   const { mkdirSync, writeFileSync } = await import("node:fs");
   const { resolve, dirname } = await import("node:path");
 
-  const schemaDir = dirname(resolve(process.argv[1] as string, ".."));
+  const schemaDir = dirname(resolve(scriptPath, ".."));
 
   const componentSchema = await generateSchema();
   const projectSchema = generateProjectSchema();
@@ -837,7 +848,7 @@ async function runSchemaCli() {
       const detail =
         fmt.stderr.toString() ||
         fmt.stdout.toString() ||
-        `exit ${fmt.exitCode ?? "null"}${fmt.signalCode ? `, signal ${fmt.signalCode}` : ""}`;
+        `exit ${fmt.exitCode}${fmt.signalCode ? `, signal ${fmt.signalCode}` : ""}`;
       console.error(`Warning: skipped oxfmt reformat of generated schemas (${detail})`);
     }
     console.error("Generated:");
@@ -854,5 +865,6 @@ async function runSchemaCli() {
 // Runs when invoked as a script or driven by a test that stages argv[1]. The build lives in an async
 // Function rather than a top-level await: Bun's test runtime drops a dynamically-imported module's
 // Top-level-await continuation on Windows. `ready` lets tests await the same sequence.
+const [, scriptPath] = process.argv;
 // oxlint-disable-next-line unicorn/prefer-top-level-await
-export const ready = process.argv[1]?.endsWith("schema.ts") ? runSchemaCli() : undefined;
+export const ready = scriptPath?.endsWith("schema.ts") ? runSchemaCli(scriptPath) : undefined;