@jxsuite/compiler 5.1.1 → 5.1.3

package/src/site/pages-discovery.ts

@@ -17,14 +17,20 @@
  */
 
 import { readFileSync, readdirSync } from "node:fs";
-import { parseJxDocument } from "@jxsuite/schema/parse";
-import { compareRoutes, fileToRoute as routeShape } from "@jxsuite/site/routes";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import { errorMessage, parseJxDocument } from "@jxsuite/schema/parse";
+import { compareRoutes, fileToRoute as routeFromFileName } from "@jxsuite/site/routes";
 import { extname, join, relative, resolve } from "node:path";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
-import type { FormatRegistry } from "@jxsuite/schema/format-registry";
-import type { JxDocument, JxPathsDef, ProjectConfig } from "@jxsuite/schema/types";
+import type {
+  FormatRegistry,
+  PathParams,
+  ResolvePathsContext,
+} from "@jxsuite/schema/format-registry";
+import type { JsonValue, JxDocument, JxPathsDef, ProjectConfig } from "@jxsuite/schema/types";
 import { localeOfRoute } from "./i18n.ts";
 import type { ResolvedI18n } from "./i18n.ts";
+import type { ProjectSections } from "./project-sections.ts";
 
 interface Route {
   urlPattern: string; // URL pattern (e.g. "/blog/:slug")
@@ -69,7 +75,7 @@ export async function readPageDocument(
         `e.g. "@jxsuite/parser".`,
     );
   }
-  return (await entry.call("parse", source)) as JxDocument;
+  return await entry.parseDocument(source);
 }
 
 /**
@@ -165,9 +171,7 @@ async function declaredTranslationKey(
   } catch {
     return null;
   }
-  return typeof doc.$translationKey === "string" && doc.$translationKey !== ""
-    ? doc.$translationKey
-    : null;
+  return isString(doc.$translationKey) && doc.$translationKey !== "" ? doc.$translationKey : null;
 }
 
 /**
@@ -230,10 +234,7 @@ async function walkDir(
     }
 
     const relativePath = relative(pagesRoot, fullPath);
-    const route = await fileToRoute(relativePath, fullPath, registry);
-    if (route) {
-      routes.push(route);
-    }
+    routes.push(await fileToRoute(relativePath, fullPath, registry));
   }
 }
 
@@ -246,14 +247,14 @@ async function walkDir(
  * @returns {Promise<Route>}
  */
 async function fileToRoute(relativePath: string, absolutePath: string, registry?: FormatRegistry) {
-  const { isCatchAll, isDynamic, params, urlPattern } = routeShape(relativePath);
+  const { isCatchAll, isDynamic, params, urlPattern } = routeFromFileName(relativePath);
 
   // Peek at the page to extract $layout if present
   let $layout: string | null = null;
   try {
     const doc = await readPageDocument(absolutePath, registry);
     const layout = doc.$layout;
-    if (typeof layout === "string") {
+    if (isString(layout)) {
       $layout = layout;
     }
   } catch {
@@ -288,16 +289,16 @@ const PATH_ENTRY_META = "_meta";
  * parameters and nothing else, and a route with no entry of its own correctly falls back to its
  * template's own modification time.
  *
- * @param {Record<string, unknown>} pathEntry
+ * @param {PathParams} pathEntry
  * @returns {string | null}
  */
-function entryMtime(pathEntry: Record<string, unknown>): string | null {
+function entryMtime(pathEntry: PathParams): string | null {
   const meta = pathEntry[PATH_ENTRY_META];
-  if (meta === null || typeof meta !== "object") {
+  if (!isJsonObject(meta)) {
     return null;
   }
-  const { mtime } = meta as { mtime?: unknown };
-  return typeof mtime === "string" && mtime !== "" ? mtime : null;
+  const { mtime } = meta;
+  return isString(mtime) && mtime !== "" ? mtime : null;
 }
 
 /**
@@ -333,7 +334,7 @@ function traversalIn(url: string): string | null {
  *
  * @param {Route[]} routes - Discovered route table
  * @param {string} projectRoot - Project root for resolving $ref paths
- * @param {Record<string, unknown>} [sections] - Loaded project sections (projectData results)
+ * @param {ProjectSections} [sections] - Loaded project sections (projectData results)
  * @param {ExtensionRegistry} [registry] - Extension registry (formats view reads non-JSON pages)
  * @param {ProjectConfig} [projectConfig] - Already-loaded project config
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
@@ -341,7 +342,7 @@ function traversalIn(url: string): string | null {
 export async function expandDynamicRoutes(
   routes: Route[],
   projectRoot: string,
-  sections: Record<string, unknown> = {},
+  sections: ProjectSections = {},
   registry?: ExtensionRegistry,
   projectConfig?: ProjectConfig,
   i18n?: ResolvedI18n | null,
@@ -351,7 +352,7 @@ export async function expandDynamicRoutes(
    * Every dynamic page's pattern, so an extension can tell a route no page produces from one a
    * different page does.
    */
-  const dynamicPatterns = routes.filter((r) => r.isDynamic).map((r) => r.urlPattern);
+  const dynamicPatterns = routes.flatMap((r) => (r.isDynamic ? [r.urlPattern] : []));
 
   for (const route of routes) {
     if (!route.isDynamic) {
@@ -360,8 +361,7 @@ export async function expandDynamicRoutes(
     }
 
     // Read the page to look for $paths
-    /** @type {Record<string, unknown>} */
-    let raw;
+    let raw: JxDocument;
     try {
       raw = await readPageDocument(route.sourcePath, registry?.formats);
     } catch {
@@ -413,15 +413,20 @@ export async function expandDynamicRoutes(
       }
 
       const mtime = entryMtime(pathEntry);
-      expanded.push({
+      /* `urlPattern` is already one of `route`'s own keys, so the spread fixes its position and
+         adding `sourceMtime` last leaves every key where the expanded route always had it. */
+      const concrete: Route = {
         ...route,
         _pathParams: params,
         isCatchAll: false,
         isDynamic: false,
         params: [],
-        ...(mtime === null ? {} : { sourceMtime: mtime }),
         urlPattern: concreteUrl,
-      });
+      };
+      if (mtime !== null) {
+        concrete.sourceMtime = mtime;
+      }
+      expanded.push(concrete);
     }
   }
 
@@ -437,25 +442,25 @@ export async function expandDynamicRoutes(
  *
  * @param {import("@jxsuite/schema/types").JxPathsDef} $paths - The $paths declaration
  * @param {string} projectRoot
- * @param {Record<string, unknown>} sections - Loaded project sections keyed by section key
+ * @param {ProjectSections} sections - Loaded project sections keyed by section key
  * @param {ExtensionRegistry} [registry]
  * @param {ProjectConfig} [projectConfig]
  * @param {string | null} [locale] - The locale the route being expanded belongs to
  * @param {Route} [route] - The dynamic page being expanded; its pattern and parameter names reach
  *   an extension's `resolvePaths` so it can produce exactly the parameters this page needs
  * @param {readonly string[]} [patterns] - The pattern of every dynamic page in the project
- * @returns {Promise<Record<string, unknown>[]>} Array of { paramName: value } objects
+ * @returns {Promise<PathParams[]>} Array of { paramName: value } objects
  */
 async function resolvePathEntries(
   $paths: JxPathsDef,
   projectRoot: string,
-  sections: Record<string, unknown>,
+  sections: ProjectSections,
   registry?: ExtensionRegistry,
   projectConfig?: ProjectConfig,
   locale?: string | null,
   route?: Pick<Route, "urlPattern" | "params">,
   patterns?: readonly string[],
-): Promise<Record<string, unknown>[]> {
+): Promise<PathParams[]> {
   // Legacy: array of param objects
   if (Array.isArray($paths)) {
     return $paths;
@@ -463,31 +468,38 @@ async function resolvePathEntries(
 
   // Explicit values: { values: ["en", "fr"], param: "lang" }
   if ("values" in $paths && Array.isArray($paths.values)) {
-    const param = typeof $paths.param === "string" ? $paths.param : "value";
-    return ($paths.values as unknown[]).map((v) => ({ [param]: v }));
+    const param = isString($paths.param) ? $paths.param : "value";
+    return $paths.values.map((v) => ({ [param]: v }));
   }
 
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
-  if ("$ref" in $paths && typeof $paths.$ref === "string" && $paths.$ref) {
+  if ("$ref" in $paths && isString($paths.$ref) && $paths.$ref) {
     const refPath = $paths.$ref;
     const filePath = resolve(projectRoot, refPath);
-    let data: unknown;
+    let data: JsonValue;
     try {
-      data = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+      // SAFETY: JSON.parse only ever yields JSON values; its `any` return type says nothing more.
+      data = JSON.parse(readFileSync(filePath, "utf8")) as JsonValue;
     } catch (error) {
-      const err = error as Error;
-      console.warn(`Warning: $paths.$ref could not load "${refPath}": ${err.message}`);
+      console.warn(`Warning: $paths.$ref could not load "${refPath}": ${errorMessage(error)}`);
       return [];
     }
     if (!Array.isArray(data)) {
       console.warn(`Warning: $paths.$ref "${refPath}" must be a JSON array`);
       return [];
     }
-    const param = typeof $paths.param === "string" ? $paths.param : "id";
-    const field = typeof $paths.field === "string" ? $paths.field : "id";
-    return (data as Record<string, unknown>[]).map((item: Record<string, unknown>) => ({
-      [param]: item[field] ?? item.id ?? String(item),
-    }));
+    const param = isString($paths.param) ? $paths.param : "id";
+    const field = isString($paths.field) ? $paths.field : "id";
+    return data.map((item) => {
+      /* A null row has no field to read and no meaningful string form: fail the build rather than
+         emit a route whose parameter is the literal "null". */
+      if (item === null) {
+        throw new TypeError(`$paths.$ref "${refPath}" contains a null entry`);
+      }
+      return {
+        [param]: (isJsonObject(item) ? (item[field] ?? item.id) : undefined) ?? String(item),
+      };
+    });
   }
 
   // Extension-discriminated: the first key with a registered resolvePaths discriminator routes
@@ -497,14 +509,20 @@ async function resolvePathEntries(
     if (!entry?.project) {
       continue;
     }
-    return (await entry.call("resolvePaths", $paths, {
+    const context: ResolvePathsContext = {
       data: sections[entry.project.key],
       locale,
       projectConfig,
       root: projectRoot,
-      ...(route === undefined ? {} : { params: route.params, urlPattern: route.urlPattern }),
-      ...(patterns === undefined ? {} : { patterns }),
-    })) as Record<string, unknown>[];
+    };
+    if (route !== undefined) {
+      context.params = route.params;
+      context.urlPattern = route.urlPattern;
+    }
+    if (patterns !== undefined) {
+      context.patterns = patterns;
+    }
+    return await entry.call("resolvePaths", $paths, context);
   }
 
   console.warn(`Warning: unrecognized $paths shape — skipping`);

package/src/site/preview-server.ts

@@ -21,24 +21,26 @@ import { MEDIA_TYPE_BY_EXTENSION } from "@jxsuite/schema/media-type";
  * Everything else is this table's own, because a shared table for `image/png` would be a second
  * source of truth for something no standard is ambiguous about.
  */
-const MIME_TYPES: Record<string, string> = {
-  ".avif": "image/avif",
-  ".css": "text/css; charset=utf-8",
-  ".gif": "image/gif",
-  ".html": "text/html; charset=utf-8",
-  ".ico": "image/x-icon",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".png": "image/png",
-  ".svg": "image/svg+xml",
-  ".txt": "text/plain; charset=utf-8",
-  ".webp": "image/webp",
-  ".woff2": "font/woff2",
-  ".xml": "application/xml; charset=utf-8",
-  ...MEDIA_TYPE_BY_EXTENSION,
-};
+const MIME_TYPES = new Map(
+  Object.entries({
+    ".avif": "image/avif",
+    ".css": "text/css; charset=utf-8",
+    ".gif": "image/gif",
+    ".html": "text/html; charset=utf-8",
+    ".ico": "image/x-icon",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".txt": "text/plain; charset=utf-8",
+    ".webp": "image/webp",
+    ".woff2": "font/woff2",
+    ".xml": "application/xml; charset=utf-8",
+    ...MEDIA_TYPE_BY_EXTENSION,
+  }),
+);
 
 /**
  * Resolve a request pathname to a file inside distDir, or null. Directory URLs (with or without a
@@ -81,7 +83,8 @@ export function startPreviewServer(distDir: string, port: number): Server {
 
     if (filePath) {
       res.writeHead(200, {
-        "Content-Type": MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream",
+        "Content-Type":
+          MIME_TYPES.get(extname(filePath).toLowerCase()) ?? "application/octet-stream",
       });
       res.end(readFileSync(filePath));
       return;

package/src/site/project-sections.ts

@@ -8,8 +8,17 @@
 
 import { createNodeFormatIO } from "./format-host.ts";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { ProjectSectionData } from "@jxsuite/schema/format-registry";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
+/* One section's `projectData` result. The host never reads inside it: it hands it to classes as
+   `_project[key]` and back to the owner's own `resolvePaths` as `data`, so the capability contract
+   in @jxsuite/schema names it and this module re-exports that name for the hosts built on it. */
+export type { ProjectSectionData } from "@jxsuite/schema/format-registry";
+
+/** Every loaded project section, keyed by its section key (`content`, `auth`, ...). */
+export type ProjectSections = Record<string, ProjectSectionData>;
+
 /**
  * Load all extension-contributed project sections.
  *
@@ -20,14 +29,14 @@ import type { ProjectConfig } from "@jxsuite/schema/types";
  * @param {string} projectRoot - Absolute path to the project root
  * @param {ProjectConfig | undefined} projectConfig - Already-loaded project config
  * @param {ExtensionRegistry} registry - The project's extension registry
- * @returns {Promise<Record<string, unknown>>} Section key → projectData result
+ * @returns {Promise<ProjectSections>} Section key → projectData result
  */
 export async function loadProjectSections(
   projectRoot: string,
   projectConfig: ProjectConfig | undefined,
   registry: ExtensionRegistry,
-): Promise<Record<string, unknown>> {
-  const sections: Record<string, unknown> = {};
+): Promise<ProjectSections> {
+  const sections: ProjectSections = {};
   const io = createNodeFormatIO(projectRoot);
   for (const entry of registry.projectContributions()) {
     const key = entry.project?.key;

package/src/site/prototype-resolver.ts

@@ -18,17 +18,20 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { importImplementation } from "./format-host.ts";
-import { isPrototypeDef } from "@jxsuite/schema/guards";
+import { isFunction, isJsonObject, isPrototypeDef, isString } from "@jxsuite/schema/guards";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type {
   JsonObject,
   JsonValue,
   JxDocument,
+  JxDocumentValue,
   JxMutableNode,
   JxPrototypeDef,
   JxStateDefinition,
+  ProjectConfig,
 } from "@jxsuite/schema/types";
+import type { ProjectSectionData, ProjectSections } from "./project-sections.ts";
 
 /**
  * Prototype names handled elsewhere (builtins + legacy content system). These are skipped by the
@@ -49,6 +52,66 @@ const RESERVED_KEYS = new Set([
   "description",
 ]);
 
+/** The route a document is being resolved for, as far as classes and `lower` read it. */
+interface PrototypeRoute {
+  sourcePath?: string;
+  _pathParams?: Record<string, string>;
+}
+
+/** Project-level context the build threads into every resolved class. */
+interface PrototypeProjectContext {
+  config?: ProjectConfig;
+  sections?: ProjectSections;
+  registry?: ExtensionRegistry;
+  registerBundle?: (specifier: string) => void;
+}
+
+/** `config._project`: the project config and root, plus every loaded section under its key. */
+interface ClassProjectContext {
+  config: ProjectConfig | null;
+  root: string;
+  [sectionKey: string]: ProjectSectionData | ProjectConfig | string | null;
+}
+
+/** `config._document`: the route being built and the page's whole state. */
+interface ClassDocumentContext {
+  route: PrototypeRoute;
+  state: Record<string, JxStateDefinition>;
+}
+
+/**
+ * The config an external class is constructed with: the def's own non-reserved keys, plus the
+ * universal `_project` and `_document` context.
+ */
+type ExternalClassConfig = Record<
+  string,
+  JxDocumentValue | ClassProjectContext | ClassDocumentContext | undefined
+>;
+
+/** A class instance that computes its value: `resolve()` answers with the JSON to bake in. */
+interface ResolvingInstance {
+  resolve: () => JsonValue | Promise<JsonValue>;
+}
+
+/**
+ * What an external class constructs (specs/extensions.md §8): either an instance that resolves its
+ * value, or an instance whose own fields ARE the value.
+ */
+type ExternalClassInstance = ResolvingInstance | JsonObject;
+
+/** An external class as its implementation module exports it. */
+type ExternalClass = new (config: ExternalClassConfig) => ExternalClassInstance;
+
+/**
+ * Whether a constructed instance computes its value through `resolve()`.
+ *
+ * @param {ExternalClassInstance} instance
+ * @returns {boolean}
+ */
+function isResolvingInstance(instance: ExternalClassInstance): instance is ResolvingInstance {
+  return isFunction(instance.resolve);
+}
+
 /**
  * Resolve all generic $prototype entries in a document's state at build time.
  *
@@ -61,27 +124,18 @@ const RESERVED_KEYS = new Set([
  *   result
  *
  * @param {JxMutableNode | JxDocument} doc - The page document (mutated in place)
- * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route - Route info
+ * @param {PrototypeRoute} route - Route info
  * @param {string} projectRoot - Absolute path to the project root
- * @param {{
- *   config?: Record<string, unknown>;
- *   sections?: Record<string, unknown>;
- *   registry?: ExtensionRegistry;
- * }} [projectContext]
- *   - Project-level context injected into all classes; `sections` holds the extension-loaded project
- *     sections keyed by section key (spread into `_project`); `registry` enables manifest class
- *     resolution and the generic `lower` capability
+ * @param {PrototypeProjectContext} [projectContext] - Project-level context injected into all
+ *   classes; `sections` holds the extension-loaded project sections keyed by section key (spread
+ *   into `_project`); `registry` enables manifest class resolution and the generic `lower`
+ *   capability
  */
 export async function resolvePrototypes(
   doc: JxMutableNode | JxDocument,
-  route: { sourcePath?: string; _pathParams?: Record<string, string> },
+  route: PrototypeRoute,
   projectRoot: string,
-  projectContext: {
-    config?: Record<string, unknown>;
-    sections?: Record<string, unknown>;
-    registry?: ExtensionRegistry;
-    registerBundle?: (specifier: string) => void;
-  } = {},
+  projectContext: PrototypeProjectContext = {},
 ) {
   const imports = doc.imports ?? {};
   const { state } = doc;
@@ -112,18 +166,18 @@ export async function resolvePrototypes(
           // A lowered def may name client modules it depends on via `$bundle`
           // (extensions.md §8.3): the site build bundles each specifier for the browser.
           // The key is host metadata, not part of the core def shape — strip it.
-          if (lowered && typeof lowered === "object" && !Array.isArray(lowered)) {
-            const bundles = (lowered as JsonObject).$bundle;
+          if (isJsonObject(lowered)) {
+            const bundles = lowered.$bundle;
             if (Array.isArray(bundles)) {
               for (const specifier of bundles) {
-                if (typeof specifier === "string") {
+                if (isString(specifier)) {
                   projectContext.registerBundle?.(specifier);
                 }
               }
             }
-            delete (lowered as JsonObject).$bundle;
+            delete lowered.$bundle;
           }
-          state[key] = lowered as JxStateDefinition;
+          state[key] = lowered;
         } catch (error) {
           console.warn(
             `prototype-resolver: failed to lower "${key}" ($prototype: "${def.$prototype}"):`,
@@ -146,8 +200,8 @@ export async function resolvePrototypes(
     try {
       const resolved = await resolveClassPrototype(def, route, projectRoot, state, projectContext);
       // Preserve timing metadata on the resolved value so compilePage() can strip it
-      if (def.timing && resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
-        (resolved as JsonObject).timing = def.timing;
+      if (def.timing && isJsonObject(resolved)) {
+        resolved.timing = def.timing;
       }
       state[key] = resolved;
     } catch (error) {
@@ -179,22 +233,19 @@ function registryClassPath(
  * Resolve a single $prototype entry via its .class.json.
  *
  * @param {JxPrototypeDef} def - The state entry definition
- * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route
+ * @param {PrototypeRoute} route
  * @param {string} projectRoot
- * @param {Record<string, unknown>} state - The full page state object
- * @param {{ config?: Record<string, unknown>; sections?: Record<string, unknown> }} projectContext
+ * @param {Record<string, JxStateDefinition>} state - The full page state object
+ * @param {PrototypeProjectContext} projectContext
  * @returns {Promise<JsonValue>} The resolved value
  */
 async function resolveClassPrototype(
   def: JxPrototypeDef,
-  route: { sourcePath?: string; _pathParams?: Record<string, string> },
+  route: PrototypeRoute,
   projectRoot: string,
-  state: Record<string, unknown>,
-  projectContext: {
-    config?: Record<string, unknown>;
-    sections?: Record<string, unknown>;
-  },
-) {
+  state: Record<string, JxStateDefinition>,
+  projectContext: PrototypeProjectContext,
+): Promise<JsonValue> {
   const src = def.$src;
   if (!src) {
     throw new Error(`$prototype "${def.$prototype}" has no $src to resolve`);
@@ -229,16 +280,17 @@ async function resolveClassPrototype(
 
   // 5. Find the exported class
   const exportName = def.$export ?? classDef.title ?? def.$prototype;
-  const ExportedClass = (mod[exportName] ??
-    (mod.default as Record<string, unknown> | undefined)?.[exportName]) as
-    | (new (config: Record<string, unknown>) => { resolve?: () => unknown })
-    | undefined;
+  /* SAFETY: what is found is the export a `.class.json` names as its implementation, which by the
+     external-class contract (specs/extensions.md §8) is a class taking this config and building an
+     ExternalClassInstance; only its presence is checked below, and the result is baked into the
+     page as JSON. */
+  const ExportedClass = (mod[exportName] ?? mod.default?.[exportName]) as ExternalClass | undefined;
   if (!ExportedClass) {
     throw new Error(`Module ${classDef.$implementation} does not export "${exportName}"`);
   }
 
   // 6. Build config — filter out reserved keys
-  const config: Record<string, unknown> = {};
+  const config: ExternalClassConfig = {};
   for (const [k, v] of Object.entries(def)) {
     if (!RESERVED_KEYS.has(k)) {
       config[k] = v;
@@ -262,8 +314,8 @@ async function resolveClassPrototype(
   // 7. Instantiate and resolve. Trust boundary: external classes contractually
   // Return JSON-serializable data (the result is baked into the compiled page).
   const instance = new ExportedClass(config);
-  if (typeof instance.resolve === "function") {
-    return (await instance.resolve()) as JsonValue;
+  if (isResolvingInstance(instance)) {
+    return await instance.resolve();
   }
-  return instance as unknown as JsonValue;
+  return instance;
 }

package/src/site/schema-command.ts

@@ -23,10 +23,12 @@ import {
   composeProjectSchemas,
   flattenSchema,
 } from "@jxsuite/schema/project-schemas";
+import { isJsonObject } from "@jxsuite/schema/guards";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import type { ExtensionInfo } from "@jxsuite/schema/extension-registry";
 import type { SchemaJsonLoader } from "@jxsuite/schema/project-schemas";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 
 const CORE_PROJECT_SPECIFIER = "@jxsuite/schema/schemas/project.core.schema.json";
 const CORE_DOCUMENT_SPECIFIER = "@jxsuite/schema/schema.json";
@@ -85,7 +87,7 @@ export async function writeProjectSchemas(projectRoot: string) {
  * (workspace hoisting leaves in-repo projects without their own node_modules).
  *
  * @param {string} projectRoot - Absolute path to the project directory
- * @returns {Promise<{ project: Record<string, unknown>; document: Record<string, unknown> }>}
+ * @returns {Promise<{ project: JsonObject; document: JsonObject }>}
  */
 export async function readBundledProjectSchemas(
   projectRoot: string,
@@ -129,17 +131,31 @@ export async function readBundledProjectSchemas(
   }
 
   const loadJson = restrictedSchemaLoader(root);
-  const projectFile =
-    composed?.projectSchema ??
-    (JSON.parse(readFileSync(projectSchemaPath, "utf8")) as Record<string, unknown>);
-  const documentFile =
-    composed?.documentSchema ??
-    (JSON.parse(readFileSync(documentSchemaPath, "utf8")) as Record<string, unknown>);
+  const projectFile = composed?.projectSchema ?? readSchemaFile(projectSchemaPath);
+  const documentFile = composed?.documentSchema ?? readSchemaFile(documentSchemaPath);
   const project = flattenSchema(await bundleSchema(projectFile, loadJson, root));
   const document = flattenSchema(await bundleSchema(documentFile, loadJson, root));
   return { document, project };
 }
 
+/**
+ * Read and parse one schema file.
+ *
+ * Every file this host bundles is a schema resource that `bundleSchema` gives an `$id` and embeds
+ * under `$defs`, and only a JSON object can be one, so anything else is refused here by name.
+ *
+ * @param {string} path - Absolute path to the schema file
+ * @returns {JsonObject}
+ */
+function readSchemaFile(path: string): JsonObject {
+  // SAFETY: JSON.parse only ever yields JSON values; its `any` return type says nothing more.
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as JsonValue;
+  if (!isJsonObject(parsed)) {
+    throw new TypeError(`Schema file "${path}" is not a JSON object`);
+  }
+  return parsed;
+}
+
 /** Packages whose schemas define the Jx document contract itself, never a project's own content. */
 const FIRST_PARTY_SCHEMA_SCOPE = "@jxsuite/";
 
@@ -215,13 +231,10 @@ export function restrictedSchemaLoader(root: string): SchemaJsonLoader {
     // Noticed for six weeks, because the artifact was only ever regenerated on the machine that
     // Had the shadow.
     if (specifier !== null && isFirstPartySchema(specifier)) {
-      return JSON.parse(readFileSync(hostResolve(specifier, path), "utf8")) as Record<
-        string,
-        unknown
-      >;
+      return readSchemaFile(hostResolve(specifier, path));
     }
     if (existsSync(abs)) {
-      return JSON.parse(readFileSync(abs, "utf8")) as Record<string, unknown>;
+      return readSchemaFile(abs);
     }
     if (specifier === null) {
       throw new Error(`Schema ref "${path}" does not exist`);
@@ -242,7 +255,7 @@ export function restrictedSchemaLoader(root: string): SchemaJsonLoader {
         );
       }
     }
-    return JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+    return readSchemaFile(resolved);
   };
 }