@jxsuite/schema 0.35.0 → 1.1.0

package/src/project-schemas.ts

@@ -0,0 +1,262 @@
+/**
+ * Per-project schema emitters (specs/extensions.md §5.2).
+ *
+ * Pure functions: they emit the generated entry documents (project.schema.json and
+ * document.schema.json) from already-resolved, project-relative fragment paths. All composition is
+ * standard JSON Schema 2020-12:
+ *
+ * - A plain `allOf` over fragment `$ref`s, closed with `unevaluatedProperties: false`;
+ * - The two well-known union resources (`PROJECT_FIELDS_SCHEMA_ID`, `DOCUMENT_PATHS_SCHEMA_ID`)
+ *   re-embedded under `$defs` with their canonical `$id`s, carrying the _effective_ unions.
+ *   Compound-document `$id` resolution makes every fragment's `$ref` to those URIs land on the
+ *   entry document's embed instead of the shipped defaults — the override mechanism.
+ *
+ * Inside the embeds all refs are canonical URIs (never relative paths): a `$ref` inside a resource
+ * with an absolute `$id` resolves against that `$id`. Relative `./node_modules/...` paths appear
+ * only in the entry document's own `allOf`/`$ref`, resolved against the file location. Hosts
+ * validating with ajv should inject an `$id` set to the entry file's URL at load time so those
+ * relative refs resolve (the committed files stay machine-path-free).
+ */
+
+import { DOCUMENT_PATHS_SCHEMA_ID, PROJECT_FIELDS_SCHEMA_ID } from "../defs/field-schema.schema";
+
+export { DOCUMENT_PATHS_SCHEMA_ID, PROJECT_FIELDS_SCHEMA_ID } from "../defs/field-schema.schema";
+
+/** The canonical $id of the core project fragment. */
+export const PROJECT_CORE_SCHEMA_ID = "https://jxsuite.com/schema/project/core/v2";
+
+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".
+   */
+  corePath: string;
+  /** Project-relative extension fragment paths, in extension declaration order. */
+  fragments: string[];
+  /**
+   * Additional field-union members beyond the core field shape and RelationshipRef, as canonical
+   * "uri#/pointer" refs (e.g. a connector's column extras). Never relative paths — they resolve
+   * against the embed's $id.
+   */
+  fieldSchemaRefs?: string[];
+}
+
+/** Emit the `project.schema.json` entry document for a project. */
+export function emitProjectSchema(inputs: ProjectSchemaInputs): Record<string, unknown> {
+  const { corePath, fragments, fieldSchemaRefs = [] } = inputs;
+  return {
+    $comment: GENERATED_SCHEMA_COMMENT,
+    $defs: {
+      Fields: {
+        $id: PROJECT_FIELDS_SCHEMA_ID,
+        anyOf: [
+          { $ref: `${PROJECT_CORE_SCHEMA_ID}#/$defs/JxFieldSchema` },
+          { $ref: `${PROJECT_CORE_SCHEMA_ID}#/$defs/RelationshipRef` },
+          ...fieldSchemaRefs.map((ref) => ({ $ref: ref })),
+        ],
+      },
+    },
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    allOf: [{ $ref: corePath }, ...fragments.map((ref) => ({ $ref: ref }))],
+    type: "object",
+    unevaluatedProperties: false,
+  };
+}
+
+// ─── 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>>;
+
+/**
+ * Bundle an entry document into a single self-contained compound schema for hosts that cannot fetch
+ * files (editor schema registration, cloud studio). Every relative-path `$ref` target is loaded
+ * through the injected loader and embedded under the entry's `$defs`, keyed by its `$id` (or a
+ * generated `urn:jx:bundled:*` one when the file declares none); the referencing `$ref`s are
+ * rewritten to those canonical URIs. Resource boundaries are preserved: embedded resources keep
+ * 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 {SchemaJsonLoader} loadJson - Loader for `$ref` target files (host-restricted)
+ * @param {string} baseDir - Directory the entry document's relative refs resolve against
+ * @returns {Promise<Record<string, unknown>>} A new, self-contained schema (the input is not
+ *   mutated)
+ */
+export async function bundleSchema(
+  entry: Record<string, unknown>,
+  loadJson: SchemaJsonLoader,
+  baseDir: string,
+): Promise<Record<string, unknown>> {
+  const bundled = structuredClone(entry);
+  const embeddedByPath = new Map<string, string>();
+  const embeddedIds = new Set<string>();
+  collectResourceIds(bundled, embeddedIds);
+  let generatedCount = 0;
+
+  /** Ordered queue of embeds so $defs insertion happens after the entry walk (stable output). */
+  const embed = async (path: string): Promise<string> => {
+    const normalized = normalizeSchemaPath(path);
+    const prior = embeddedByPath.get(normalized);
+    if (prior !== undefined) {
+      return prior;
+    }
+    let resource: Record<string, unknown>;
+    try {
+      resource = structuredClone(await loadJson(normalized));
+    } catch (error) {
+      throw new Error(
+        `bundleSchema: cannot load $ref target "${normalized}": ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    const ownId =
+      typeof resource.$id === "string" && hasUriScheme(resource.$id) ? resource.$id : null;
+    generatedCount += ownId === null ? 1 : 0;
+    const id = ownId ?? `urn:jx:bundled:${generatedCount}`;
+    embeddedByPath.set(normalized, id);
+    if (embeddedIds.has(id)) {
+      // The canonical resource is already part of the compound document — refs land on it.
+      return id;
+    }
+    embeddedIds.add(id);
+    resource.$id = id;
+    await rewrite(resource, schemaDirOf(normalized), true);
+    const defs = (bundled.$defs ??= {}) as Record<string, unknown>;
+    defs[id] = resource;
+    return id;
+  };
+
+  /**
+   * 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> => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        await rewrite(item, fileDir);
+      }
+      return;
+    }
+    if (node === null || typeof node !== "object") {
+      return;
+    }
+    const obj = node as Record<string, unknown>;
+    let scope = fileDir;
+    if (!isRoot && typeof obj.$id === "string" && 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)) {
+      const hashIndex = ref.indexOf("#");
+      const target = hashIndex === -1 ? ref : ref.slice(0, hashIndex);
+      const fragment = hashIndex === -1 ? "" : ref.slice(hashIndex);
+      if (target) {
+        const id = await embed(`${scope}/${target}`);
+        obj.$ref = `${id}${fragment}`;
+      }
+    }
+    for (const value of Object.values(obj)) {
+      await rewrite(value, scope);
+    }
+  };
+
+  await rewrite(bundled, normalizeSchemaPath(baseDir), true);
+  return bundled;
+}
+
+/** Collect every absolute `$id` already present in a document (embeds like the field union). */
+function collectResourceIds(node: unknown, out: Set<string>): void {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectResourceIds(item, out);
+    }
+    return;
+  }
+  if (node === null || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (typeof obj.$id === "string" && hasUriScheme(obj.$id)) {
+    out.add(obj.$id);
+  }
+  for (const value of Object.values(obj)) {
+    collectResourceIds(value, out);
+  }
+}
+
+/** True when a ref/id carries a URI scheme (https:, urn:, file:) — i.e. is not a relative path. */
+function hasUriScheme(ref: string): boolean {
+  return /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(ref);
+}
+
+/** Normalize a path to forward slashes, resolving "." and ".." segments (environment-agnostic). */
+function normalizeSchemaPath(path: string): string {
+  const slashed = path.replaceAll("\\", "/");
+  const absolute = slashed.startsWith("/");
+  const parts: string[] = [];
+  for (const segment of slashed.split("/")) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (parts.length > 0 && parts.at(-1) !== "..") {
+        parts.pop();
+      } else if (!absolute) {
+        parts.push("..");
+      }
+      continue;
+    }
+    parts.push(segment);
+  }
+  return (absolute ? "/" : "") + parts.join("/");
+}
+
+/** The directory portion of a normalized schema path ("." when there is none). */
+function schemaDirOf(path: string): string {
+  const index = path.lastIndexOf("/");
+  if (index === -1) {
+    return ".";
+  }
+  return index === 0 ? "/" : path.slice(0, index);
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export interface DocumentSchemaInputs {
+  /**
+   * Project-relative path of the core document schema, e.g.
+   * "./node_modules/@jxsuite/schema/schema.json".
+   */
+  corePath: string;
+  /** Canonical "uri#/pointer" refs unioned into the paths resource, in declaration order. */
+  pathsValueRefs: string[];
+}
+
+/** Emit the `document.schema.json` entry document for a project. */
+export function emitDocumentSchema(inputs: DocumentSchemaInputs): Record<string, unknown> {
+  const { corePath, pathsValueRefs } = inputs;
+  return {
+    $comment: GENERATED_SCHEMA_COMMENT,
+    $defs: {
+      // With no contributed paths shapes the embed stays permissive — core `$paths` forms
+      // (arrays, values, $ref) are validated by the core schema itself.
+      PathsValue:
+        pathsValueRefs.length > 0
+          ? {
+              $id: DOCUMENT_PATHS_SCHEMA_ID,
+              anyOf: pathsValueRefs.map((ref) => ({ $ref: ref })),
+            }
+          : { $id: DOCUMENT_PATHS_SCHEMA_ID },
+    },
+    $ref: corePath,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+  };
+}

package/src/schema.ts

@@ -58,11 +58,14 @@ import {
 } from "../defs/element-def.schema";
 import { typedStateDefSchema } from "../defs/typed-state-def.schema";
 import { functionDefSchema } from "../defs/function-def.schema";
+import { statementListSchema, statementSchema } from "../defs/statement.schema";
 import { externalClassDefSchema } from "../defs/external-class-def.schema";
 import { pureTypeDefSchema } from "../defs/pure-type-def.schema";
 import {
   assignmentOperatorSchema,
   binaryOperatorSchema,
+  callOperatorSchema,
+  conditionalOperatorSchema,
   expressionEntrySchema,
   expressionLiteralSchema,
   expressionNodeSchema,
@@ -71,8 +74,10 @@ import {
   mapFilterMethodSchema,
   noArgMethodSchema,
   oneArgMethodSchema,
+  pureMethodSchema,
   reduceMethodSchema,
   spliceMethodSchema,
+  switchOperatorSchema,
   unaryOperatorSchema,
 } from "../defs/expression-node.schema";
 import {
@@ -90,7 +95,13 @@ import {
   formatDefSchema,
   studioHintsSchema,
 } from "../defs/class-def.schema";
-import { contentTypeDefSchema } from "../defs/content-type-def.schema";
+import { extensionManifestSchema } from "../defs/extension-manifest.schema";
+import {
+  DOCUMENT_PATHS_SCHEMA_ID,
+  PROJECT_FIELDS_SCHEMA_ID,
+  jxFieldSchemaDef,
+  relationshipRefSchema,
+} from "../defs/field-schema.schema";
 import { imageConfigSchema } from "../defs/image-config.schema";
 import { projectConfigSchema } from "../defs/project-config.schema";
 
@@ -212,6 +223,10 @@ export async function generateSchema() {
       ExpressionOperand: expressionOperandSchema,
       UnaryOperator: unaryOperatorSchema,
       BinaryOperator: binaryOperatorSchema,
+      ConditionalOperator: conditionalOperatorSchema,
+      SwitchOperator: switchOperatorSchema,
+      CallOperator: callOperatorSchema,
+      PureMethod: pureMethodSchema,
       AssignmentOperator: assignmentOperatorSchema,
       NoArgMethod: noArgMethodSchema,
       OneArgMethod: oneArgMethodSchema,
@@ -220,6 +235,8 @@ export async function generateSchema() {
       MapFilterMethod: mapFilterMethodSchema,
       ExpressionNode: expressionNodeSchema,
       ExpressionEntry: expressionEntrySchema,
+      Statement: statementSchema,
+      StatementList: statementListSchema,
 
       // Element defs — with webref data injected
       ElementDef: {
@@ -261,7 +278,6 @@ export async function generateSchema() {
       JsonSchemaType: jsonSchemaTypeSchema,
       HeadEntry: headEntrySchema,
       ImageConfig: imageConfigSchema,
-      ContentTypeDef: contentTypeDefSchema,
     },
     $id: "https://jxsuite.com/schema/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -395,23 +411,97 @@ export async function generateSchema() {
 export function generateProjectSchema() {
   return {
     $defs: {
-      ContentTypeDef: contentTypeDefSchema,
       ImageConfig: imageConfigSchema,
     },
     $id: "https://jxsuite.com/schema/project/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
-    additionalProperties: false,
     description:
       "Schema for Jx project.json files. " +
       "A project.json file is the root anchor file for a Jx project, " +
-      "declaring site metadata, default settings, global styles, content types, " +
-      "and build configuration.",
+      "declaring site metadata, default settings, global styles, extensions, " +
+      "and build configuration. Open by design: extension-contributed sections " +
+      "are opaque top-level keys; the generated per-project entry document " +
+      "(project.schema.json) closes the composition.",
     properties: projectConfigSchema.properties,
     title: "Jx Project",
     type: "object",
   };
 }
 
+// ─── Project Core Fragment Generator ─────────────────────────────────────────
+
+/**
+ * The core fragment of the composed per-project schema (specs/extensions.md §5.1): core
+ * project.json properties only — no extension sections — and deliberately open, because closure
+ * (`unevaluatedProperties: false`) happens in the generated entry document. Publishes the
+ * `JxFieldSchema` and `RelationshipRef` defs the entry document unions into the `jxFieldSchema`
+ * dynamic anchor.
+ */
+export function generateProjectCoreSchema() {
+  return {
+    $defs: {
+      ImageConfig: imageConfigSchema,
+      JxFieldSchema: jxFieldSchemaDef,
+      RelationshipRef: relationshipRefSchema,
+    },
+    $id: "https://jxsuite.com/schema/project/core/v2",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    description:
+      "Core fragment of the Jx project.json schema. Open by design: extension fragments " +
+      "contribute their own top-level sections and the generated per-project entry document " +
+      "(project.schema.json) closes the composition. See specs/extensions.md §5.",
+    properties: projectConfigSchema.properties,
+    title: "Jx Project Core",
+    type: "object",
+  };
+}
+
+// ─── Union Resource Generators ───────────────────────────────────────────────
+
+/**
+ * The shipped DEFAULT field-union resource. The generated per-project entry document re-embeds a
+ * resource under the same $id with the effective union (adding extension extras); by standard
+ * compound-document $id resolution the embed shadows this default wherever both are in play.
+ */
+export function generateProjectFieldsSchema() {
+  return {
+    $id: PROJECT_FIELDS_SCHEMA_ID,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    anyOf: [
+      { $ref: "https://jxsuite.com/schema/project/core/v2#/$defs/JxFieldSchema" },
+      { $ref: "https://jxsuite.com/schema/project/core/v2#/$defs/RelationshipRef" },
+    ],
+    description:
+      "Default field-schema union for section entry schemas: the core field shape plus " +
+      "relationship references. Per-project entry documents override this resource with the " +
+      "effective union. See specs/extensions.md §5.3.",
+    title: "Jx Project Field Union",
+  };
+}
+
+/** The shipped DEFAULT $paths-value resource: permissive until extensions contribute shapes. */
+export function generateDocumentPathsSchema() {
+  return {
+    $id: DOCUMENT_PATHS_SCHEMA_ID,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    description:
+      "Default $paths-value union for documents. Per-project entry documents override this " +
+      "resource with the union of extension-contributed paths shapes.",
+    title: "Jx Document Paths Union",
+  };
+}
+
+// ─── Extension Manifest Schema Generator ─────────────────────────────────────
+
+export function generateExtensionManifestSchema() {
+  return {
+    $id: "https://jxsuite.com/schema/extension-manifest/v1",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "Jx Extension Manifest",
+    ...extensionManifestSchema,
+  };
+}
+
 // ─── Class Schema Generator ─────────────────────────────────────────────────
 
 export function generateClassSchema() {
@@ -545,7 +635,7 @@ export async function validateDocument(doc: Record<string, unknown>) {
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 async function runSchemaCli() {
-  const { writeFileSync } = await import("node:fs");
+  const { mkdirSync, writeFileSync } = await import("node:fs");
   const { resolve, dirname } = await import("node:path");
 
   const schemaDir = dirname(resolve(process.argv[1] as string, ".."));
@@ -553,10 +643,18 @@ async function runSchemaCli() {
   const componentSchema = await generateSchema();
   const projectSchema = generateProjectSchema();
   const classSchema = generateClassSchema();
+  const projectCoreSchema = generateProjectCoreSchema();
+  const manifestSchema = generateExtensionManifestSchema();
+  const fieldsSchema = generateProjectFieldsSchema();
+  const pathsSchema = generateDocumentPathsSchema();
 
   const componentStr = JSON.stringify(componentSchema, null, 2);
   const projectStr = JSON.stringify(projectSchema, null, 2);
   const classStr = JSON.stringify(classSchema, null, 2);
+  const projectCoreStr = JSON.stringify(projectCoreSchema, null, 2);
+  const manifestStr = JSON.stringify(manifestSchema, null, 2);
+  const fieldsStr = JSON.stringify(fieldsSchema, null, 2);
+  const pathsStr = JSON.stringify(pathsSchema, null, 2);
 
   const [out] = process.argv.slice(2);
 
@@ -567,10 +665,23 @@ async function runSchemaCli() {
     writeFileSync(resolve(schemaDir, "schema.json"), componentStr, "utf8");
     writeFileSync(resolve(schemaDir, "project-schema.json"), projectStr, "utf8");
     writeFileSync(resolve(schemaDir, "class-schema.json"), classStr, "utf8");
+    mkdirSync(resolve(schemaDir, "schemas"), { recursive: true });
+    writeFileSync(
+      resolve(schemaDir, "schemas", "project.core.schema.json"),
+      projectCoreStr,
+      "utf8",
+    );
+    writeFileSync(resolve(schemaDir, "schemas", "project.fields.schema.json"), fieldsStr, "utf8");
+    writeFileSync(resolve(schemaDir, "schemas", "document.paths.schema.json"), pathsStr, "utf8");
+    writeFileSync(resolve(schemaDir, "extension-manifest.schema.json"), manifestStr, "utf8");
     console.error("Generated:");
     console.error("  schema.json (component)");
     console.error("  project-schema.json");
     console.error("  class-schema.json");
+    console.error("  schemas/project.core.schema.json");
+    console.error("  schemas/project.fields.schema.json");
+    console.error("  schemas/document.paths.schema.json");
+    console.error("  extension-manifest.schema.json");
   }
 }
 

package/src/validate-project.ts

@@ -0,0 +1,144 @@
+/**
+ * Validate-project — project.json validation against the generated per-project entry schema
+ * (specs/extensions.md §5.4).
+ *
+ * Node-only by design (mirrors the dynamic-ajv-import pattern of `validateDocument`): reads
+ * `<root>/project.json` and `<root>/project.schema.json`, compiles the entry document with
+ * ajv-2020, and resolves its relative `$ref`s through a file loader restricted to the project root
+ * and its node_modules. The entry file's URL is injected as `$id` at load time so the committed,
+ * machine-path-free relative refs resolve.
+ *
+ * When a `./node_modules/...` ref does not exist on disk (workspace hoisting leaves in-repo
+ * starters without their own node_modules), the loader falls back to host resolution of the bare
+ * specifier — the same project-first-then-host order as createNodeFormatIO.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export interface ProjectValidationResult {
+  valid: boolean;
+  errors: unknown[] | null;
+}
+
+// Minimal structural types for the optional `ajv` peer dependency (no direct dependency, and it
+// Ships no types usable from here) — same pattern as validateDocument in src/schema.ts.
+interface AjvValidateFn {
+  (doc: unknown): boolean;
+  errors?: unknown[] | null;
+}
+interface AjvInstance {
+  compileAsync: (schema: unknown) => Promise<AjvValidateFn>;
+}
+type AjvCtor = new (opts: {
+  allErrors: boolean;
+  strict: boolean;
+  loadSchema: (uri: string) => Promise<Record<string, unknown>>;
+}) => AjvInstance;
+
+/**
+ * Validate `<projectRoot>/project.json` against `<projectRoot>/project.schema.json`.
+ *
+ * Validation failures are data (`{ valid: false, errors }`); infrastructure failures — missing
+ * files, unresolvable refs, refs escaping the project root — throw.
+ *
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @returns {Promise<ProjectValidationResult>}
+ */
+export async function validateProjectFile(projectRoot: string): Promise<ProjectValidationResult> {
+  const root = resolve(projectRoot);
+  const projectPath = resolve(root, "project.json");
+  const schemaPath = resolve(root, "project.schema.json");
+
+  if (!existsSync(projectPath)) {
+    throw new Error(`project.json not found in ${root}`);
+  }
+  if (!existsSync(schemaPath)) {
+    throw new Error(
+      `project.schema.json not found in ${root} — run \`jx schema\` to generate it from ` +
+        `project.json#/extensions`,
+    );
+  }
+
+  const project = JSON.parse(readFileSync(projectPath, "utf8")) as Record<string, unknown>;
+  const entrySchema = JSON.parse(readFileSync(schemaPath, "utf8")) as Record<string, unknown>;
+  // The committed entry document is machine-path-free; injecting its file URL as $id makes its
+  // Relative ./node_modules/... refs resolve against the project root.
+  entrySchema.$id = pathToFileURL(schemaPath).href;
+
+  let Ajv: AjvCtor;
+  try {
+    // The entry document is JSON Schema 2020-12, so use the matching Ajv build.
+    ({ default: Ajv } = (await import("ajv/dist/2020")) as { default: AjvCtor });
+  } catch (error) {
+    throw new Error("Project validation requires ajv: bun add ajv", { cause: error });
+  }
+
+  const ajv = new Ajv({
+    allErrors: true,
+    loadSchema: (uri) => loadProjectSchemaRef(uri, root),
+    strict: false,
+  });
+
+  const validate = await ajv.compileAsync(entrySchema);
+  const valid = validate(project);
+  return { errors: validate.errors ?? null, valid };
+}
+
+/**
+ * Restricted schema loader: only `file:` URLs inside the project root are served. Missing files
+ * under `<root>/node_modules/` fall back to host resolution of the corresponding bare specifier
+ * (in-repo starters have no local node_modules; the fragments still ship with the host).
+ *
+ * @param {string} uri - The `$ref` target ajv could not resolve from already-loaded resources
+ * @param {string} root - Absolute project root
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function loadProjectSchemaRef(uri: string, root: string): Promise<Record<string, unknown>> {
+  if (!uri.startsWith("file:")) {
+    throw new Error(
+      `Cannot resolve schema ref "${uri}": only project-relative file refs are loadable ` +
+        `(canonical URIs must resolve from already-loaded fragments)`,
+    );
+  }
+
+  const filePath = fileURLToPath(uri);
+  const rel = relative(root, filePath);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`Schema ref "${uri}" escapes the project root ${root}`);
+  }
+
+  if (existsSync(filePath)) {
+    return JSON.parse(readFileSync(filePath, "utf8")) as Record<string, unknown>;
+  }
+
+  // Host fallback: <root>/node_modules/<specifier> is absent — resolve the specifier through the
+  // Project's own resolution first, then the host's (workspace symlinks resolve transparently).
+  const posixRel = rel.split("\\").join("/");
+  const marker = "node_modules/";
+  const markerIndex = posixRel.lastIndexOf(marker);
+  if (markerIndex === -1) {
+    throw new Error(`Schema ref "${uri}" does not exist`);
+  }
+  const specifier = posixRel.slice(markerIndex + marker.length);
+
+  let resolved: string;
+  try {
+    const projRequire = createRequire(resolve(root, "package.json"));
+    resolved = projRequire.resolve(specifier);
+  } catch {
+    try {
+      const selfRequire = createRequire(import.meta.url);
+      resolved = selfRequire.resolve(specifier);
+    } catch (error) {
+      throw new Error(
+        `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
+          `project or the host`,
+        { cause: error },
+      );
+    }
+  }
+  return JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+}