@jxsuite/compiler 0.28.5 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.28.5",
+  "version": "0.30.1",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -35,20 +35,21 @@
   "scripts": {
     "prepare": "bun build src/compiler.ts src/cli.ts --outdir=dist --format=esm --minify --target=node",
     "build": "bun run prepare",
+    "build:metafile": "bun build src/compiler.ts src/cli.ts --outdir=dist --format=esm --minify --target=node --metafile=metafile.json",
     "build:site": "bun src/cli.ts build",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^15.3.6",
-    "@jxsuite/parser": "^0.28.5",
-    "@jxsuite/runtime": "^0.28.5",
-    "@jxsuite/schema": "^0.28.5",
-    "sharp": "^0.35.1"
+    "@apidevtools/json-schema-ref-parser": "^15.4.0",
+    "@jxsuite/parser": "^0.30.1",
+    "@jxsuite/runtime": "^0.30.1",
+    "@jxsuite/schema": "^0.30.1",
+    "sharp": "^0.35.2"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.2",
+    "@happy-dom/global-registrator": "^20.10.6",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/cli.ts

@@ -9,11 +9,16 @@
 
 import { resolve } from "node:path";
 
-const args = process.argv.slice(2);
-const [command] = args;
+// The CLI body runs inside an async function rather than via top-level await: when a test pulls this
+// Entry in with a dynamic import(), Bun's test runtime drops the continuation after a top-level await
+// (it never resumes on Windows), so the build step would silently never run. `ready` lets the
+// In-process CLI harness await the same sequence.
+async function main() {
+  const args = process.argv.slice(2);
+  const [command] = args;
 
-if (!command || command === "--help" || command === "-h") {
-  console.log(`Usage: jx <command> [options]
+  if (!command || command === "--help" || command === "-h") {
+    console.log(`Usage: jx <command> [options]
 
 Commands:
   build [root]   Build a Jx site to dist/
@@ -21,39 +26,43 @@ Commands:
 Options:
   --verbose      Print detailed build progress
   --no-clean     Don't clean outDir before building`);
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-if (command === "build") {
-  const rest = args.slice(1);
-  const flags = new Set(rest.filter((a) => a.startsWith("--")));
-  const positional = rest.find((a) => !a.startsWith("--"));
+  if (command === "build") {
+    const rest = args.slice(1);
+    const flags = new Set(rest.filter((a) => a.startsWith("--")));
+    const positional = rest.find((a) => !a.startsWith("--"));
 
-  const projectRoot = resolve(positional ?? ".");
-  const verbose = flags.has("--verbose");
-  const clean = !flags.has("--no-clean");
+    const projectRoot = resolve(positional ?? ".");
+    const verbose = flags.has("--verbose");
+    const clean = !flags.has("--no-clean");
 
-  console.log(`Building site from ${projectRoot}...`);
+    console.log(`Building site from ${projectRoot}...`);
 
-  try {
-    const { buildSite } = await import("./site/site-build.ts");
-    const result = await buildSite(projectRoot, { clean, verbose });
+    try {
+      const { buildSite } = await import("./site/site-build.ts");
+      const result = await buildSite(projectRoot, { clean, verbose });
 
-    if (result.errors.length > 0) {
-      console.error(`\nBuild completed with ${result.errors.length} error(s):`);
-      for (const err of result.errors) {
-        console.error(`  - ${err}`);
+      if (result.errors.length > 0) {
+        console.error(`\nBuild completed with ${result.errors.length} error(s):`);
+        for (const err of result.errors) {
+          console.error(`  - ${err}`);
+        }
+        process.exit(1);
       }
+
+      console.log(`\nDone: ${result.routes} routes → ${result.files} files`);
+    } catch (error) {
+      const err = error as Error;
+      console.error(`Build failed: ${err.message}`);
       process.exit(1);
     }
-
-    console.log(`\nDone: ${result.routes} routes → ${result.files} files`);
-  } catch (error) {
-    const err = error as Error;
-    console.error(`Build failed: ${err.message}`);
+  } else {
+    console.error(`Unknown command: ${command}\nRun "jx --help" for usage.`);
     process.exit(1);
   }
-} else {
-  console.error(`Unknown command: ${command}\nRun "jx --help" for usage.`);
-  process.exit(1);
 }
+
+// oxlint-disable-next-line unicorn/prefer-top-level-await
+export const ready = main();

package/src/compile-cli.ts

@@ -1,12 +1,20 @@
 #!/usr/bin/env node
 import { runCli } from "./compiler.ts";
 
-const [src, out] = process.argv.slice(2);
-if (src) {
-  try {
-    await runCli(src, out);
-  } catch (error) {
-    console.error(error);
-    process.exit(1);
+// Body wrapped in an async function rather than a top-level await: Bun's test runtime drops the
+// Continuation after a dynamically-imported module's top-level await (it never resumes on Windows),
+// Which would skip the error handling. `ready` lets the in-process CLI harness await the sequence.
+async function main() {
+  const [src, out] = process.argv.slice(2);
+  if (src) {
+    try {
+      await runCli(src, out);
+    } catch (error) {
+      console.error(error);
+      process.exit(1);
+    }
   }
 }
+
+// oxlint-disable-next-line unicorn/prefer-top-level-await
+export const ready = main();

package/src/compiler.ts

@@ -22,13 +22,9 @@ import {
   isDynamic,
   tagNameToClassName,
 } from "./shared.ts";
-import { compileServer, compileSiteServer } from "./targets/compile-server.ts";
+import { compileServer } from "./targets/compile-server.ts";
 
-import {
-  compileElement,
-  compileElementPage,
-  emitElementModule,
-} from "./targets/compile-element.ts";
+import { emitElementModule } from "./targets/compile-element.ts";
 import { compileStaticPage } from "./targets/compile-static.ts";
 import { compileClient } from "./targets/compile-client.ts";
 import { isClassDef } from "@jxsuite/schema/guards";
@@ -37,14 +33,10 @@ import type { JxDocument, JxStyle } from "@jxsuite/schema/types";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 
 // Re-exports for consumers
-export {
-  isDynamic,
-  compileServer,
-  compileSiteServer,
-  compileElement,
-  compileElementPage,
-  compileClient,
-};
+export { isDynamic } from "./shared.ts";
+export { compileServer, compileSiteServer } from "./targets/compile-server.ts";
+export { compileElement, compileElementPage } from "./targets/compile-element.ts";
+export { compileClient } from "./targets/compile-client.ts";
 
 // ─── Entry ────────────────────────────────────────────────────────────────────
 

package/src/shared.ts

@@ -7,10 +7,12 @@
  */
 
 import { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
-import { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 import {
+  childrenContainArray,
   isExpressionDef,
   isFunctionDef,
+  isMappedArray,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
@@ -22,7 +24,6 @@ import type { ExpressionNode } from "@jxsuite/runtime/expression";
 import type {
   JsonValue,
   JxElement,
-  JxMappedArray,
   JxMutableNode,
   JxPrototypeDef,
   JxRef,
@@ -32,15 +33,9 @@ import type {
 } from "@jxsuite/schema/types";
 
 // Re-export runtime utilities used by submodules
-export {
-  camelToKebab,
-  toCSSText,
-  RESERVED_KEYS,
-  compileExpression,
-  isMutating,
-  evaluateExpression,
-};
-export type { ExpressionNode };
+export { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
+export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
 export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.32";
@@ -110,10 +105,7 @@ export function isDynamic(def: JxElement | JxMutableNode | string) {
   if (def.$switch) {
     return true;
   }
-  if (
-    !Array.isArray(def.children) &&
-    (def.children as JxMappedArray | undefined)?.$prototype === "Array"
-  ) {
+  if (isMappedArray(def) || childrenContainArray(def.children)) {
     return true;
   }
 
@@ -170,10 +162,7 @@ export function isNodeDynamic(def: JxElement | JxMutableNode | string) {
   if (def.$switch) {
     return true;
   }
-  if (
-    !Array.isArray(def.children) &&
-    (def.children as JxMappedArray | undefined)?.$prototype === "Array"
-  ) {
+  if (isMappedArray(def) || childrenContainArray(def.children)) {
     return true;
   }
 
@@ -252,9 +241,9 @@ export function createCompileContext(
   scopeDefs: Record<string, unknown> = {},
   media: Record<string, string> = {},
 ): CompileContext {
-  const scope = raw?.state
+  const scope: Record<string, unknown> = raw?.state
     ? buildInitialScope(raw.state, parentScope)
-    : (parentScope ?? Object.create(null));
+    : (parentScope ?? (Object.create(null) as Record<string, unknown>));
   return { media, scope, scopeDefs };
 }
 
@@ -267,7 +256,7 @@ export function buildInitialScope(
   defs: Record<string, JxStateDefinition> = {},
   parentScope: Record<string, unknown> | null = null,
 ) {
-  const scope = Object.create(parentScope ?? null);
+  const scope = Object.create(parentScope ?? null) as Record<string, unknown>;
 
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def !== "object" || def === null || Array.isArray(def)) {
@@ -306,7 +295,9 @@ export function buildInitialScope(
     if (isFunctionDef(def)) {
       if (def.body) {
         const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
-        const fn = new Function("state", ...names, def.body);
+        const fn = new Function("state", ...names, def.body) as (
+          state: Record<string, unknown>,
+        ) => unknown;
         if (def.body.includes("return")) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
@@ -393,7 +384,7 @@ export function resolveRefValue(refValue: unknown, scope: Record<string, unknown
   }
   if (refValue.startsWith("$map/")) {
     const parts = refValue.split("/");
-    const [, key] = parts;
+    const key = parts[1]!;
     const base = (scope.$map as Record<string, unknown> | undefined)?.[key] ?? scope[`$map/${key}`];
     return parts.length > 2 ? getPathValue(base, parts.slice(2).join("/")) : base;
   }
@@ -417,10 +408,16 @@ export function evaluateStaticTemplate(str: string, scope: Record<string, unknow
   try {
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
     if (singleExprMatch) {
-      const fn = new Function("state", "$map", `return (${singleExprMatch[1]})`);
+      const fn = new Function("state", "$map", `return (${singleExprMatch[1]})`) as (
+        state: Record<string, unknown>,
+        $map: unknown,
+      ) => unknown;
       return fn(scope, scope?.$map);
     }
-    const fn = new Function("state", "$map", `return \`${str}\``);
+    const fn = new Function("state", "$map", `return \`${str}\``) as (
+      state: Record<string, unknown>,
+      $map: unknown,
+    ) => unknown;
     return fn(scope, scope?.$map);
   } catch {
     return null;
@@ -632,7 +629,7 @@ export function compileStyles(
           if (mProps) {
             rules.push(`${atRule} { ${selector} { ${mProps} } }`);
           }
-          for (const [sel, sub] of Object.entries(/** @type {Record<string, unknown>} */ val)) {
+          for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
             if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
               continue;
             }
@@ -753,7 +750,7 @@ function emitNestedElement(
       if (mProps) {
         rules.push(`${atRule} { ${selector} { ${mProps} } }`);
       }
-      for (const [sel, sub] of Object.entries(/** @type {Record<string, unknown>} */ val)) {
+      for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
         if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
           continue;
         }
@@ -995,8 +992,7 @@ function _walkSrc(def: JxElement | JxMutableNode | string, srcs: Set<string>) {
  * @returns {{ key: string; exportName: string; src: string }[]}
  */
 export function collectServerEntries(doc: JxElement) {
-  /** @type {Map<string, { key: string; exportName: string; src: string }>} */
-  const entries = new Map();
+  const entries = new Map<string, { key: string; exportName: string; src: string }>();
   _walkServerEntries(doc, entries);
   return [...entries.values()];
 }
@@ -1028,7 +1024,7 @@ function _walkServerEntries(
 
 // ─── Component pre-rendering ─────────────────────────────────────────────────
 
-const SELF_CLOSING = new Set<string>([
+export const SELF_CLOSING = new Set<string>([
   "input",
   "br",
   "hr",

package/src/site/content-loader.ts

@@ -21,6 +21,7 @@ import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registr
 import type {
   ContentTypeDef,
   ContentTypeSchema,
+  ContentTypeSchemaField,
   JxMutableNode,
   ProjectConfig,
 } from "@jxsuite/schema/types";
@@ -36,16 +37,16 @@ import type { ContentLoaderEntry } from "@jxsuite/parser/types";
  * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
 function loadJSONEntries(filePath: string) {
-  const raw = JSON.parse(readFileSync(filePath, "utf8"));
+  const raw = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
   if (Array.isArray(raw)) {
-    return raw.map((item: Record<string, unknown>, i: number) => ({
+    return (raw as Record<string, unknown>[]).map((item: Record<string, unknown>, i: number) => ({
       body: null,
       data: item,
       id: (item.id as string) ?? `${basename(filePath, ".json")}-${i}`,
     }));
   }
   // Single object file — filename is the id
-  const rawObj: Record<string, unknown> = raw;
+  const rawObj = raw as Record<string, unknown>;
   return [
     {
       body: null,
@@ -108,7 +109,7 @@ export async function loadContentTypes(
 ) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) {
-    return new Map();
+    return new Map<string, ContentLoaderEntry[]>();
   }
 
   const { config } = result;
@@ -359,7 +360,8 @@ export function resolveContentTypeRefs(
       continue;
     }
 
-    for (const [field, def] of Object.entries(schema.properties)) {
+    for (const [field, rawDef] of Object.entries(schema.properties)) {
+      const def = rawDef as ContentTypeSchemaField;
       if (!def.$ref?.startsWith("#/contentTypes/")) {
         continue;
       }

package/src/site/context-injection.ts

@@ -36,7 +36,7 @@ export function injectContext(
   doc: JxDocument,
   projectConfig: ProjectConfig,
   route: SiteRoute,
-  contentTypes = new Map<string, ContentLoaderEntry[]>(),
+  _contentTypes = new Map<string, ContentLoaderEntry[]>(),
   projectRoot: string | null = null,
 ) {
   if (!doc.state) {

package/src/site/image-cache.ts

@@ -94,13 +94,13 @@ export function cacheKey(srcPath: string, config: ImageConfig) {
  * @param {string} projectRoot
  * @returns {CacheManifest}
  */
-export function loadCache(projectRoot: string) {
+export function loadCache(projectRoot: string): CacheManifest {
   const manifestPath = resolve(getImageCacheDir(projectRoot), "manifest.json");
   if (!existsSync(manifestPath)) {
     return { entries: {}, version: 1 };
   }
   try {
-    return JSON.parse(readFileSync(manifestPath, "utf8"));
+    return JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
   } catch {
     return { entries: {}, version: 1 };
   }

package/src/site/image-optimizer.ts

@@ -10,7 +10,8 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, extname, resolve } from "node:path";
 import { createRequire } from "node:module";
-import type { FormatEnum } from "sharp";
+// Sharp 0.35 only has a default export (function merged with a types namespace).
+import type SharpNS from "sharp";
 
 export interface ImageVariant {
   width: number; // Pixel width of the variant
@@ -41,8 +42,14 @@ export interface ImageConfig {
   remoteDomains?: string[];
 }
 
-// oxlint-disable-next-line typescript/consistent-type-imports -- sharp is an optional native dep loaded lazily; its `export =` module type is only nameable via import()
-type SharpModule = typeof import("sharp");
+type SharpModule = typeof SharpNS;
+/**
+ * Accepted output-format type, derived from the Sharp instance's own toFormat signature. Reaching
+ * into the `SharpNS.FormatEnum` namespace instead is fragile: sharp ships as `export = sharp`, so
+ * whether a default type-import exposes the merged namespace depends on esModuleInterop resolution
+ * (differs local vs CI).
+ */
+type SharpFormat = Parameters<ReturnType<SharpModule>["toFormat"]>[0];
 
 let _sharp: SharpModule | null = null;
 
@@ -175,7 +182,7 @@ export async function processImage(srcPath: string, cacheImgDir: string, config:
       const quality = config.quality[format as keyof ImageConfig["quality"]] ?? 80;
       const task = sharp(srcPath)
         .resize(width)
-        .toFormat(format as keyof FormatEnum, { quality })
+        .toFormat(format as SharpFormat, { quality })
         .toFile(absolutePath)
         .then(() => {});
 

package/src/site/image-transform.ts

@@ -340,7 +340,7 @@ async function transformImgNode(
         imageRefs.set(absoluteSrc, manifest);
       }
 
-      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
     }
   }
@@ -384,8 +384,8 @@ async function transformInnerHtmlImages(
   const replacements = [];
 
   for (const m of html.matchAll(IMG_TAG_RE)) {
-    const [tag] = m;
-    const [, attrs] = m;
+    const tag = m[0]!;
+    const attrs = m[1]!;
 
     if (SRCSET_ATTR_RE.test(attrs)) {
       continue;
@@ -400,7 +400,7 @@ async function transformInnerHtmlImages(
     }
 
     // Attribute values in pre-rendered innerHTML are entity-escaped — decode for processing
-    const src = srcMatch[1].replaceAll("&", "&");
+    const src = srcMatch[1]!.replaceAll("&", "&");
     const remote = isAllowedRemote(src, config);
     if (!remote && shouldSkip(src)) {
       continue;
@@ -425,7 +425,7 @@ async function transformInnerHtmlImages(
         imageRefs.set(absoluteSrc as string, manifest);
       }
 
-      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
     }
     if (!srcset) {

package/src/site/pages-discovery.ts

@@ -169,7 +169,7 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
   // Convert [param] → :param and [...param] → *
   const urlPattern = urlPath.replaceAll(
     /\[\.\.\.(\w+)\]|\[(\w+)\]/g,
-    (match: string, spread: string, named: string) => {
+    (_match: string, spread: string, named: string) => {
       if (spread) {
         isCatchAll = true;
         isDynamic = true;
@@ -319,10 +319,9 @@ function resolvePathEntries(
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
   if ("$ref" in $paths && $paths.$ref) {
     const filePath = resolve(projectRoot, $paths.$ref);
-    /** @type {Record<string, unknown>[]} */
-    let data;
+    let data: unknown;
     try {
-      data = JSON.parse(readFileSync(filePath, "utf8"));
+      data = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
     } catch (error) {
       const err = error as Error;
       console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
@@ -334,7 +333,7 @@ function resolvePathEntries(
     }
     const param = $paths.param ?? "id";
     const field = $paths.field ?? "id";
-    return data.map((item: Record<string, unknown>) => ({
+    return (data as Record<string, unknown>[]).map((item: Record<string, unknown>) => ({
       [param]: item[field] ?? item.id ?? String(item),
     }));
   }