@jxsuite/compiler 0.28.2 → 0.28.3

package/src/site/pages-discovery.ts

@@ -12,10 +12,11 @@
  * prefix)
  */
 
-import { readdirSync, readFileSync } from "node:fs";
-import { resolve, relative, extname, join } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { parseJxDocument } from "@jxsuite/schema/parse";
+import { extname, join, relative, resolve } from "node:path";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { JxDocument, JxPathsDef } from "@jxsuite/schema/types";
 import type { ContentLoaderEntry } from "@jxsuite/parser/types";
 
 interface Route {
@@ -43,7 +44,7 @@ export async function readPageDocument(
 ): Promise<JxDocument> {
   const source = readFileSync(filePath, "utf8");
   if (filePath.endsWith(".json")) {
-    return JSON.parse(source);
+    return parseJxDocument(source, filePath);
   }
   const ext = extname(filePath).toLowerCase();
   const entry = registry?.byExtension(ext, "parse");
@@ -71,8 +72,12 @@ export async function discoverPages(pagesDir: string, registry?: FormatRegistry)
 
   // Sort: static routes first, then by specificity (more segments = more specific)
   routes.sort((a, b) => {
-    if (a.isDynamic !== b.isDynamic) return a.isDynamic ? 1 : -1;
-    if (a.isCatchAll !== b.isCatchAll) return a.isCatchAll ? 1 : -1;
+    if (a.isDynamic !== b.isDynamic) {
+      return a.isDynamic ? 1 : -1;
+    }
+    if (a.isCatchAll !== b.isCatchAll) {
+      return a.isCatchAll ? 1 : -1;
+    }
     return a.urlPattern.localeCompare(b.urlPattern);
   });
 
@@ -102,21 +107,29 @@ async function walkDir(
 
     if (entry.isDirectory()) {
       // Skip underscore-prefixed directories
-      if (entry.name.startsWith("_")) continue;
+      if (entry.name.startsWith("_")) {
+        continue;
+      }
       await walkDir(fullPath, pagesRoot, routes, pageExtensions, registry);
       continue;
     }
 
     // Only process .json and registered page-format files
     const ext = extname(entry.name).toLowerCase();
-    if (!pageExtensions.has(ext)) continue;
+    if (!pageExtensions.has(ext)) {
+      continue;
+    }
 
     // Skip underscore-prefixed files (local components, not routes)
-    if (entry.name.startsWith("_")) continue;
+    if (entry.name.startsWith("_")) {
+      continue;
+    }
 
     const relativePath = relative(pagesRoot, fullPath);
     const route = await fileToRoute(relativePath, fullPath, registry);
-    if (route) routes.push(route);
+    if (route) {
+      routes.push(route);
+    }
   }
 }
 
@@ -136,7 +149,7 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
   // Normalize path separators
   urlPath = urlPath.split("\\").join("/");
 
-  // index files map to their parent directory
+  // Index files map to their parent directory
   if (urlPath.endsWith("/index")) {
     urlPath = urlPath.slice(0, -6) || "/";
   } else if (urlPath === "index") {
@@ -144,7 +157,9 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
   }
 
   // Ensure leading slash
-  if (!urlPath.startsWith("/")) urlPath = "/" + urlPath;
+  if (!urlPath.startsWith("/")) {
+    urlPath = `/${urlPath}`;
+  }
 
   // Extract parameters from bracket syntax
   const params: string[] = [];
@@ -152,7 +167,7 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
   let isCatchAll = false;
 
   // Convert [param] → :param and [...param] → *
-  const urlPattern = urlPath.replace(
+  const urlPattern = urlPath.replaceAll(
     /\[\.\.\.(\w+)\]|\[(\w+)\]/g,
     (match: string, spread: string, named: string) => {
       if (spread) {
@@ -168,25 +183,25 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
   );
 
   // Peek at the page to extract $layout if present
-  /** @type {string | null} */
-  let $layout = null;
+  let $layout: string | null = null;
   try {
     const doc = await readPageDocument(absolutePath, registry);
-    if (typeof doc.$layout === "string") {
-      $layout = doc.$layout;
+    const layout = doc.$layout;
+    if (typeof layout === "string") {
+      $layout = layout;
     }
   } catch {
     // Skip unreadable files — will error during compilation
   }
 
   return {
-    urlPattern,
-    sourcePath: absolutePath,
-    relativePath,
-    isDynamic,
+    $layout,
     isCatchAll,
+    isDynamic,
     params,
-    $layout,
+    relativePath,
+    sourcePath: absolutePath,
+    urlPattern,
   };
 }
 
@@ -200,14 +215,15 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
  *
  * @param {Route[]} routes - Discovered route table
  * @param {string} projectRoot - Project root for resolving $ref paths
- * @param {Map<string, any[]>} [contentTypes] - Loaded content types (from content-loader)
+ * @param {Map<string, ContentLoaderEntry[]>} [contentTypes] - Loaded content types (from
+ *   content-loader)
  * @param {FormatRegistry} [registry] - Format registry for reading non-JSON dynamic pages
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
 export async function expandDynamicRoutes(
   routes: Route[],
   projectRoot: string,
-  contentTypes: Map<string, any[]> = new Map(),
+  contentTypes = new Map<string, ContentLoaderEntry[]>(),
   registry?: FormatRegistry,
 ) {
   const expanded: Route[] = [];
@@ -237,18 +253,20 @@ export async function expandDynamicRoutes(
 
     for (const pathEntry of pathEntries) {
       let concreteUrl = route.urlPattern;
+      const params: Record<string, string> = {};
       for (const [param, value] of Object.entries(pathEntry)) {
-        concreteUrl = concreteUrl.replace(`:${param}`, value as string);
-        concreteUrl = concreteUrl.replace("*", value as string);
+        params[param] = String(value);
+        concreteUrl = concreteUrl.replace(`:${param}`, params[param]);
+        concreteUrl = concreteUrl.replace("*", params[param]);
       }
 
       expanded.push({
         ...route,
-        urlPattern: concreteUrl,
-        isDynamic: false,
+        _pathParams: params,
         isCatchAll: false,
+        isDynamic: false,
         params: [],
-        _pathParams: pathEntry,
+        urlPattern: concreteUrl,
       });
     }
   }
@@ -259,19 +277,23 @@ export async function expandDynamicRoutes(
 /**
  * Resolve $paths into an array of param objects.
  *
- * @param {any} $paths - The $paths declaration
+ * @param {import("@jxsuite/schema/types").JxPathsDef} $paths - The $paths declaration
  * @param {string} projectRoot
- * @param {Map<string, any[]>} contentTypes
- * @returns {Record<string, any>[]} Array of { paramName: value } objects
+ * @param {Map<string, ContentLoaderEntry[]>} contentTypes
+ * @returns {Record<string, unknown>[]} Array of { paramName: value } objects
  */
-function resolvePathEntries($paths: any, projectRoot: string, contentTypes: Map<string, any[]>) {
+function resolvePathEntries(
+  $paths: JxPathsDef,
+  projectRoot: string,
+  contentTypes: Map<string, ContentLoaderEntry[]>,
+): Record<string, unknown>[] {
   // Legacy: array of param objects
   if (Array.isArray($paths)) {
     return $paths;
   }
 
   // Content type-based: { contentType: "blog", param: "slug", field: "id" }
-  if ($paths.contentType) {
+  if ("contentType" in $paths && $paths.contentType) {
     const entries = contentTypes.get($paths.contentType);
     if (!entries || entries.length === 0) {
       console.warn(
@@ -289,20 +311,20 @@ function resolvePathEntries($paths: any, projectRoot: string, contentTypes: Map<
   }
 
   // Explicit values: { values: ["en", "fr"], param: "lang" }
-  if (Array.isArray($paths.values)) {
+  if ("values" in $paths && Array.isArray($paths.values)) {
     const param = $paths.param ?? "value";
-    return $paths.values.map((v: string) => ({ [param]: v }));
+    return $paths.values.map((v) => ({ [param]: v }));
   }
 
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
-  if ($paths.$ref) {
+  if ("$ref" in $paths && $paths.$ref) {
     const filePath = resolve(projectRoot, $paths.$ref);
     /** @type {Record<string, unknown>[]} */
     let data;
     try {
       data = JSON.parse(readFileSync(filePath, "utf8"));
-    } catch (e) {
-      const err = e as Error;
+    } catch (error) {
+      const err = error as Error;
       console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
       return [];
     }

package/src/site/prototype-resolver.ts

@@ -18,7 +18,15 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { importImplementation } from "./format-host.ts";
-import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
+import { isPrototypeDef } from "@jxsuite/schema/guards";
+import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
+import type {
+  JsonObject,
+  JsonValue,
+  JxDocument,
+  JxMutableNode,
+  JxPrototypeDef,
+} from "@jxsuite/schema/types";
 
 /**
  * Prototype names handled elsewhere (builtins + legacy content system). These are skipped by the
@@ -65,20 +73,30 @@ export async function resolvePrototypes(
   } = {},
 ) {
   const imports = doc.imports ?? {};
-  const state = doc.state;
-  if (!state) return;
+  const { state } = doc;
+  if (!state) {
+    return;
+  }
 
   for (const [key, def] of Object.entries(state)) {
-    if (!def || typeof def !== "object" || !def.$prototype) continue;
-    if (SKIP_PROTOTYPES.has(def.$prototype)) continue;
+    if (!isPrototypeDef(def)) {
+      continue;
+    }
+    if (SKIP_PROTOTYPES.has(def.$prototype)) {
+      continue;
+    }
     // Only resolve timing: "compiler" (or unset timing with a .class.json mapping).
     // Leave timing: "server" and timing: "client" for their respective pipelines.
-    if (def.timing && def.timing !== "compiler") continue;
+    if (def.timing && def.timing !== "compiler") {
+      continue;
+    }
 
     // Look up in imports if no $src already set
     if (!def.$src) {
       const mapped = imports[def.$prototype];
-      if (!mapped) continue;
+      if (!mapped) {
+        continue;
+      }
       def.$src = mapped;
     }
 
@@ -86,13 +104,13 @@ export async function resolvePrototypes(
       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 Record<string, unknown>).timing = def.timing;
+        (resolved as JsonObject).timing = def.timing;
       }
       state[key] = resolved;
-    } catch (err) {
+    } catch (error) {
       console.warn(
         `prototype-resolver: failed to resolve "${key}" ($prototype: "${def.$prototype}"):`,
-        (err as Error).message,
+        errorMessage(error),
       );
     }
   }
@@ -101,15 +119,15 @@ export async function resolvePrototypes(
 /**
  * Resolve a single $prototype entry via its .class.json.
  *
- * @param {Record<string, any>} def - The state entry definition
+ * @param {JxPrototypeDef} def - The state entry definition
  * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route
  * @param {string} projectRoot
  * @param {Record<string, unknown>} state - The full page state object
  * @param {{ config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> }} projectContext
- * @returns {Promise<any>} The resolved value
+ * @returns {Promise<JsonValue>} The resolved value
  */
 async function resolveClassPrototype(
-  def: Record<string, any>,
+  def: JxPrototypeDef,
   route: { sourcePath?: string; _pathParams?: Record<string, string> },
   projectRoot: string,
   state: Record<string, unknown>,
@@ -119,6 +137,9 @@ async function resolveClassPrototype(
   },
 ) {
   const src = def.$src;
+  if (!src) {
+    throw new Error(`$prototype "${def.$prototype}" has no $src to resolve`);
+  }
 
   // 1. Resolve .class.json path — handles both npm specifiers and relative paths
   let classJsonPath;
@@ -128,14 +149,14 @@ async function resolveClassPrototype(
       ? resolve(dirname(route.sourcePath), src)
       : resolve(projectRoot, src);
   } else {
-    // npm/bare specifier — use createRequire from the project root to walk node_modules
+    // Npm/bare specifier — use createRequire from the project root to walk node_modules
     const require = createRequire(resolve(projectRoot, "package.json"));
     classJsonPath = require.resolve(src);
   }
 
   // 2. Read and parse .class.json
-  const classJsonText = readFileSync(classJsonPath, "utf-8");
-  const classDef = JSON.parse(classJsonText);
+  const classJsonText = readFileSync(classJsonPath, "utf8");
+  const classDef = parseClassDef(classJsonText, classJsonPath);
 
   if (!classDef.$implementation) {
     throw new Error(`${src} has no $implementation field`);
@@ -158,9 +179,11 @@ async function resolveClassPrototype(
   }
 
   // 6. Build config — filter out reserved keys
-  const config: Record<string, any> = {};
+  const config: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(def)) {
-    if (!RESERVED_KEYS.has(k)) config[k] = v;
+    if (!RESERVED_KEYS.has(k)) {
+      config[k] = v;
+    }
   }
 
   // Auto-set basePath from the page's directory if the config has `src` but no `basePath`
@@ -176,10 +199,11 @@ async function resolveClassPrototype(
   };
   config._document = { route, state };
 
-  // 7. Instantiate and resolve
+  // 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();
+    return (await instance.resolve()) as JsonValue;
   }
-  return instance;
+  return instance as unknown as JsonValue;
 }