@jxsuite/schema 0.35.0 → 1.0.0

package/src/extension-registry.ts

@@ -0,0 +1,270 @@
+/**
+ * Extension registry — manifest-driven discovery of extension packages (specs/extensions.md).
+ *
+ * A project declares extensions in project.json (`"extensions": ["@jxsuite/parser", ...]`); each
+ * extension package ships a `jx-extension.json` manifest enumerating its classes and schema
+ * fragments. Hosts resolve `<specifier>/jx-extension.json` (bare specifiers through the package's
+ * exports map, project-first), read each listed `.class.json`, and dispatch through the declared
+ * admission blocks (`format` | `project` | `server` | `connector`) and capability roles.
+ *
+ * All I/O is injected via FormatHostIO so the same module serves node and browser hosts. The
+ * format-dispatch view reuses FormatRegistry (including its extension/capability conflict checks).
+ */
+
+import { FormatEntry, FormatRegistry } from "./format-registry";
+import type { FormatHostIO } from "./format-registry";
+
+export type {
+  CapabilityInfo,
+  ConnectorBlock,
+  ExtensionCapability,
+  FormatHostIO,
+  ProjectBlock,
+  ServerBlock,
+} from "./format-registry";
+export { EXTENSION_CAPABILITIES, FormatEntry, FormatRegistry } from "./format-registry";
+
+/** The well-known manifest filename every extension package exports. */
+export const EXTENSION_MANIFEST = "jx-extension.json";
+
+export interface ExtensionManifest {
+  name: string;
+  title?: string;
+  description?: string;
+  classes?: Record<string, string>;
+  /**
+   * Schema fragments the package contributes: `project` (project.json sections), `document` ($paths
+   * shapes), and `fields` — a fragment whose `$defs` members are unioned into the per-project
+   * field-schema resource (extension field extras, specs/extensions.md §5.3).
+   */
+  schemas?: { project?: string; document?: string; fields?: string };
+}
+
+export interface ExtensionInfo {
+  /** The project.json `extensions` entry that produced this extension. */
+  specifier: string;
+  /** Resolved absolute path of the jx-extension.json manifest. */
+  manifestPath: string;
+  manifest: ExtensionManifest;
+  /** Class entries in manifest order. */
+  classes: FormatEntry[];
+  /** Resolved absolute fragment paths, when the manifest declares them. */
+  schemas: { project?: string; document?: string; fields?: string };
+}
+
+export type SchemaFragmentKind = "project" | "document" | "fields";
+
+export class ExtensionRegistry {
+  #extensions: ExtensionInfo[];
+  #classes: FormatEntry[];
+  #formats: FormatRegistry;
+
+  constructor(extensions: ExtensionInfo[]) {
+    this.#extensions = extensions;
+    this.#classes = extensions.flatMap((e) => e.classes);
+
+    // Class names are the $prototype-visible namespace: duplicates across extensions are a
+    // Configuration error (a project-local `imports` entry may still shadow a manifest class —
+    // That overlay happens at the host, not here).
+    const byName = new Map<string, string>();
+    for (const ext of extensions) {
+      for (const cls of ext.classes) {
+        const prior = byName.get(cls.name);
+        if (prior && prior !== ext.specifier) {
+          throw new Error(
+            `Extension conflict: "${prior}" and "${ext.specifier}" both provide a class named "${cls.name}"`,
+          );
+        }
+        byName.set(cls.name, ext.specifier);
+      }
+    }
+
+    // Section keys are exclusive (specs/extensions.md §3.1).
+    const byKey = new Map<string, FormatEntry>();
+    for (const entry of this.#classes) {
+      if (!entry.project) {
+        continue;
+      }
+      const prior = byKey.get(entry.project.key);
+      if (prior) {
+        throw new Error(
+          `Extension conflict: "${prior.name}" and "${entry.name}" both claim the project section "${entry.project.key}"`,
+        );
+      }
+      byKey.set(entry.project.key, entry);
+    }
+
+    // Server mounts own disjoint /_jx/ subtrees (specs/extensions.md §11).
+    const byBasePath = new Map<string, FormatEntry>();
+    for (const entry of this.#classes) {
+      if (!entry.server) {
+        continue;
+      }
+      const { basePath } = entry.server;
+      if (!basePath.startsWith("/_jx/")) {
+        throw new Error(
+          `Extension "${entry.name}": server basePath "${basePath}" must be under /_jx/`,
+        );
+      }
+      const prior = byBasePath.get(basePath);
+      if (prior) {
+        throw new Error(
+          `Extension conflict: "${prior.name}" and "${entry.name}" both mount "${basePath}"`,
+        );
+      }
+      byBasePath.set(basePath, entry);
+    }
+
+    // The format-dispatch view; its constructor enforces (extension, capability) exclusivity.
+    this.#formats = new FormatRegistry(this.#classes.filter((e) => e.extensions.length > 0));
+  }
+
+  get extensions(): readonly ExtensionInfo[] {
+    return this.#extensions;
+  }
+
+  /** Every class entry across all extensions, in declaration order. */
+  get classes(): readonly FormatEntry[] {
+    return this.#classes;
+  }
+
+  /** File-extension dispatch view (parse/serialize/discover/load lookups). */
+  get formats(): FormatRegistry {
+    return this.#formats;
+  }
+
+  byName(name: string): FormatEntry | undefined {
+    return this.#classes.find((e) => e.name === name);
+  }
+
+  /** Classes owning a project.json section, in declaration order. */
+  projectContributions(): FormatEntry[] {
+    return this.#classes.filter((e) => e.project !== null);
+  }
+
+  byProjectKey(key: string): FormatEntry | undefined {
+    return this.#classes.find((e) => e.project?.key === key);
+  }
+
+  /** The class whose `resolvePaths` capability declares this `$paths` discriminator key. */
+  byPathsDiscriminator(key: string): FormatEntry | undefined {
+    return this.#classes.find((e) => e.capabilities.resolvePaths?.discriminator === key);
+  }
+
+  /** Server-mount classes, sorted by `server.order` (ascending; default 100), then name. */
+  serverMounts(): FormatEntry[] {
+    return this.#classes
+      .filter((e) => e.server !== null)
+      .toSorted(
+        (a, b) =>
+          (a.server?.order ?? 100) - (b.server?.order ?? 100) || a.name.localeCompare(b.name),
+      );
+  }
+
+  /** Connection-provider classes (connector block). */
+  connectors(): FormatEntry[] {
+    return this.#classes.filter((e) => e.connector !== null);
+  }
+
+  /** Resolved fragment paths of the given kind, in extension declaration order. */
+  schemaFragments(kind: SchemaFragmentKind): string[] {
+    return this.#extensions
+      .map((e) => e.schemas[kind])
+      .filter((p): p is string => typeof p === "string");
+  }
+}
+
+/**
+ * Build a registry from a project's `extensions` list.
+ *
+ * Specifiers are bare package names (resolved project-first through the package's exports map) or
+ * relative paths. Unlike the legacy imports scan, everything here is explicit — an unresolvable
+ * manifest or class file is an error, not a silent skip.
+ *
+ * @param {string[] | undefined} extensions - The project.json `extensions` array
+ * @param {FormatHostIO} io - Injected host I/O
+ * @param {string} base - Reference file for relative resolution (convention: `<root>/project.json`)
+ */
+export async function buildExtensionRegistry(
+  extensions: string[] | undefined,
+  io: FormatHostIO,
+  base: string,
+): Promise<ExtensionRegistry> {
+  const infos: ExtensionInfo[] = [];
+  for (const specifier of extensions ?? []) {
+    infos.push(await loadExtension(specifier, io, base));
+  }
+  return new ExtensionRegistry(infos);
+}
+
+async function loadExtension(
+  specifier: string,
+  io: FormatHostIO,
+  base: string,
+): Promise<ExtensionInfo> {
+  let manifestPath: string;
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    const dir = io.resolvePath(base, specifier);
+    manifestPath = io.resolvePath(`${dir}/package.json`, `./${EXTENSION_MANIFEST}`);
+  } else {
+    try {
+      manifestPath = io.resolvePath(base, `${specifier}/${EXTENSION_MANIFEST}`);
+    } catch (error) {
+      throw new Error(
+        `Extension "${specifier}" is not resolvable: it must export ${EXTENSION_MANIFEST} ` +
+          `(is the package installed, and does its exports map include it?): ${errorMessage(error)}`,
+        { cause: error },
+      );
+    }
+  }
+
+  let manifest: ExtensionManifest;
+  try {
+    manifest = (await io.loadJson(manifestPath)) as unknown as ExtensionManifest;
+  } catch (error) {
+    throw new Error(
+      `Extension "${specifier}": cannot read manifest ${manifestPath}: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+  if (!manifest || typeof manifest !== "object" || typeof manifest.name !== "string") {
+    throw new Error(`Extension "${specifier}": ${EXTENSION_MANIFEST} must declare a "name"`);
+  }
+  if (!specifier.startsWith(".") && manifest.name !== specifier) {
+    throw new Error(
+      `Extension "${specifier}": manifest name "${manifest.name}" does not match the specifier`,
+    );
+  }
+
+  const classes: FormatEntry[] = [];
+  for (const [name, ref] of Object.entries(manifest.classes ?? {})) {
+    const classPath = io.resolvePath(manifestPath, ref);
+    let classDef: Record<string, unknown>;
+    try {
+      classDef = await io.loadJson(classPath);
+    } catch (error) {
+      throw new Error(
+        `Extension "${specifier}": cannot read class "${name}" at ${classPath}: ${errorMessage(error)}`,
+        { cause: error },
+      );
+    }
+    classes.push(new FormatEntry(name, classPath, classDef, io));
+  }
+
+  const schemas: ExtensionInfo["schemas"] = {};
+  if (manifest.schemas?.project) {
+    schemas.project = io.resolvePath(manifestPath, manifest.schemas.project);
+  }
+  if (manifest.schemas?.document) {
+    schemas.document = io.resolvePath(manifestPath, manifest.schemas.document);
+  }
+  if (manifest.schemas?.fields) {
+    schemas.fields = io.resolvePath(manifestPath, manifest.schemas.fields);
+  }
+
+  return { specifier, manifestPath, manifest, classes, schemas };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/format-registry.ts

@@ -19,6 +19,34 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
   "load",
 ];
 
+/**
+ * All well-known static capability roles across admission blocks (specs/extensions.md §8): format
+ * roles plus project-section (`projectData`, `resolvePaths`), compile-away (`lower`), server-mount
+ * (`mount`), and connector (`dialect`, `deploySchema`, `bindings`, `testConnection`) roles.
+ */
+export type ExtensionCapability =
+  | FormatCapability
+  | "projectData"
+  | "resolvePaths"
+  | "lower"
+  | "mount"
+  | "dialect"
+  | "deploySchema"
+  | "bindings"
+  | "testConnection";
+
+export const EXTENSION_CAPABILITIES: readonly ExtensionCapability[] = [
+  ...FORMAT_CAPABILITIES,
+  "projectData",
+  "resolvePaths",
+  "lower",
+  "mount",
+  "dialect",
+  "deploySchema",
+  "bindings",
+  "testConnection",
+];
+
 export type FormatTiming = "compiler" | "server" | "client";
 
 export type FormatDocumentKind = "page" | "component" | "content";
@@ -62,6 +90,32 @@ export interface CapabilityInfo {
   identifier: string;
   /** Environments allowed to call directly; others round-trip via the dev server. */
   timing: FormatTiming[];
+  /** For `resolvePaths`: the `$paths` key that routes to this class. */
+  discriminator?: string;
+}
+
+/** A class owns a project.json section iff its descriptor carries a `project` block. */
+export interface ProjectBlock {
+  key: string;
+  title?: string;
+  description?: string;
+  referenceable?: boolean;
+}
+
+/** A class mounts routes in the site worker/dev server iff it carries a `server` block. */
+export interface ServerBlock {
+  basePath: string;
+  order?: number;
+  module?: string;
+}
+
+/** A class provides database connections iff it carries a `connector` block. */
+export interface ConnectorBlock {
+  provider: string;
+  kind: "sqlite" | "postgres";
+  local?: string;
+  serve?: string;
+  [key: string]: unknown;
 }
 
 export interface FormatHostIO {
@@ -78,12 +132,16 @@ interface ClassMethodLike {
   identifier?: string;
   scope?: string;
   timing?: string[];
+  discriminator?: string;
 }
 
 interface ClassDefLike {
   title?: string;
   $implementation?: string;
   format?: FormatBlock;
+  project?: ProjectBlock;
+  server?: ServerBlock;
+  connector?: ConnectorBlock;
   $studio?: StudioHints;
   $defs?: { methods?: Record<string, ClassMethodLike> };
   [key: string]: unknown;
@@ -101,7 +159,10 @@ export class FormatEntry {
   readonly exportTarget: boolean;
   readonly remote: boolean;
   readonly studio: StudioHints | null;
-  readonly capabilities: Partial<Record<FormatCapability, CapabilityInfo>>;
+  readonly project: ProjectBlock | null;
+  readonly server: ServerBlock | null;
+  readonly connector: ConnectorBlock | null;
+  readonly capabilities: Partial<Record<ExtensionCapability, CapabilityInfo>>;
 
   #io: FormatHostIO;
   #implementation: Promise<Record<string, unknown>> | null = null;
@@ -112,13 +173,18 @@ export class FormatEntry {
     this.classDef = classDef;
     this.#io = io;
 
-    const format = classDef.format as FormatBlock;
-    this.extensions = (format.extensions ?? []).map((e) => e.toLowerCase());
-    this.mediaType = format.mediaType ?? null;
-    this.documentKinds = format.documentKinds ?? [];
-    this.exportTarget = format.exportTarget === true;
-    this.remote = format.remote === true;
+    // The format block is optional: entries also represent project/server/connector classes
+    // (specs/extensions.md §6). Absent block → no extensions claimed.
+    const { format } = classDef;
+    this.extensions = (format?.extensions ?? []).map((e) => e.toLowerCase());
+    this.mediaType = format?.mediaType ?? null;
+    this.documentKinds = format?.documentKinds ?? [];
+    this.exportTarget = format?.exportTarget === true;
+    this.remote = format?.remote === true;
     this.studio = classDef.$studio ?? null;
+    this.project = classDef.project ?? null;
+    this.server = classDef.server ?? null;
+    this.connector = classDef.connector ?? null;
     this.capabilities = extractCapabilities(classDef);
   }
 
@@ -137,7 +203,7 @@ export class FormatEntry {
   }
 
   /** Invoke a capability's static method on the implementation class. */
-  async call(capability: FormatCapability, ...args: unknown[]): Promise<unknown> {
+  async call(capability: ExtensionCapability, ...args: unknown[]): Promise<unknown> {
     const cap = this.capabilities[capability];
     if (!cap) {
       throw new Error(`Format class "${this.name}" does not declare a "${capability}" capability`);
@@ -264,18 +330,22 @@ export async function buildFormatRegistry(
 
 function extractCapabilities(
   classDef: ClassDefLike,
-): Partial<Record<FormatCapability, CapabilityInfo>> {
-  const out: Partial<Record<FormatCapability, CapabilityInfo>> = {};
+): Partial<Record<ExtensionCapability, CapabilityInfo>> {
+  const out: Partial<Record<ExtensionCapability, CapabilityInfo>> = {};
   const methods = classDef.$defs?.methods ?? {};
   for (const [key, method] of Object.entries(methods)) {
-    const role = method.role as FormatCapability | undefined;
-    if (!role || !FORMAT_CAPABILITIES.includes(role)) {
+    const role = method.role as ExtensionCapability | undefined;
+    if (!role || !EXTENSION_CAPABILITIES.includes(role)) {
       continue;
     }
-    out[role] = {
+    const info: CapabilityInfo = {
       identifier: method.identifier ?? key,
       timing: (method.timing as FormatTiming[] | undefined) ?? DEFAULT_TIMING,
     };
+    if (typeof method.discriminator === "string") {
+      info.discriminator = method.discriminator;
+    }
+    out[role] = info;
   }
   return out;
 }

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",
+  };
+}