@jxsuite/compiler 5.1.2 → 5.1.3

package/src/site/format-host.ts

@@ -12,8 +12,14 @@ import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { buildExtensionRegistry, EXTENSION_MANIFEST } from "@jxsuite/schema/extension-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
-import type { FormatHostIO, FormatRegistry, ProjectBlock } from "@jxsuite/schema/format-registry";
-import type { ProjectConfig } from "@jxsuite/schema/types";
+import type {
+  FormatHostIO,
+  ImplementationExport,
+  ProjectBlock,
+  StudioHints,
+} from "@jxsuite/schema/format-registry";
+import { isJsonObject } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, ProjectConfig } from "@jxsuite/schema/types";
 
 export type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registry";
@@ -27,9 +33,10 @@ export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registr
  * built module is JavaScript), and .js → .ts.
  *
  * @param {string} path - Absolute path to the implementation module
- * @returns {Promise<Record<string, unknown>>}
+ * @returns {Promise<ImplementationExport>} The module's namespace object, whose named exports (and
+ *   `default`) are read by name
  */
-export async function importImplementation(path: string): Promise<Record<string, unknown>> {
+export async function importImplementation(path: string): Promise<ImplementationExport> {
   const candidates = [path];
   const srcSeg = `${sep}src${sep}`;
   const distSeg = `${sep}dist${sep}`;
@@ -131,7 +138,11 @@ export function probeExtension(projectRoot: string, name: string): ExtensionReso
     // Not shipped by this host either.
   }
 
-  return { host, project, ...(manifestPath === undefined ? {} : { manifestPath }) };
+  const resolution: ExtensionResolution = { host, project };
+  if (manifestPath !== undefined) {
+    resolution.manifestPath = manifestPath;
+  }
+  return resolution;
 }
 
 /** Build the extension registry for a project from its project.json `extensions` array. */
@@ -146,20 +157,6 @@ export async function buildProjectExtensionRegistry(
   );
 }
 
-/**
- * Format-dispatch view of the project's extension registry.
- *
- * @deprecated Part-3 cleanup: the desktop app still imports this; use
- *   `buildProjectExtensionRegistry(...).then((r) => r.formats)` instead.
- */
-export async function buildProjectFormatRegistry(
-  projectRoot: string,
-  projectConfig?: ProjectConfig,
-): Promise<FormatRegistry> {
-  const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
-  return registry.formats;
-}
-
 // ─── Studio extensions payload ────────────────────────────────────────────────
 
 /** One project-section contribution on the studio wire (specs/extensions.md §9/§9.1). */
@@ -169,12 +166,24 @@ export interface ExtensionsPayloadContribution {
   /** The class descriptor's `project` admission block. */
   project: ProjectBlock;
   /** The class descriptor's `$studio` block (settings section vocabulary), when declared. */
-  studio: Record<string, unknown> | null;
+  studio: StudioHints | null;
   /**
-   * The section's value schema — `properties[<key>]` of the extension's project fragment — or null
-   * when the extension ships no project fragment (or it lacks the key).
+   * The section's value schema — `properties[<key>]` of the extension's project fragment, which
+   * JSON Schema lets be a boolean as well as an object — or null when the extension ships no
+   * project fragment (or it lacks the key).
    */
-  entrySchema: Record<string, unknown> | null;
+  entrySchema: JsonValue;
+}
+
+/** One manifest class of an extension on the studio wire. */
+export interface ExtensionsPayloadClass {
+  name: string;
+  /** The class's resolved descriptor path. */
+  path: string;
+  /** Present on a plain state class: one with no admission blocks. */
+  state?: boolean;
+  /** The descriptor's `$studio.stateDefaults` hint (specs/extensions.md §10), when it is an object. */
+  stateDefaults?: JsonObject;
 }
 
 /** One extension package on the studio wire (the formats route's `extensions` sibling array). */
@@ -191,12 +200,7 @@ export interface ExtensionsPayloadEntry {
    * carry `state: true` plus their `$studio.stateDefaults` hint (specs/extensions.md §10), so the
    * studio can offer them in its add-state picker and seed new defs (e.g. `timing: "client"`).
    */
-  classes: {
-    name: string;
-    path: string;
-    state?: boolean;
-    stateDefaults?: Record<string, unknown>;
-  }[];
+  classes: ExtensionsPayloadClass[];
 }
 
 /**
@@ -211,13 +215,13 @@ export interface ExtensionsPayloadEntry {
 export function buildExtensionsPayload(registry: ExtensionRegistry): ExtensionsPayloadEntry[] {
   const payload: ExtensionsPayloadEntry[] = [];
   for (const ext of registry.extensions) {
-    let fragmentProperties: Record<string, Record<string, unknown>> = {};
+    let fragmentProperties: JsonObject = {};
     if (ext.schemas.project) {
       try {
-        const fragment = JSON.parse(readFileSync(ext.schemas.project, "utf8")) as {
-          properties?: Record<string, Record<string, unknown>>;
-        };
-        fragmentProperties = fragment.properties ?? {};
+        // SAFETY: JSON.parse only ever yields JSON values; its `any` return type says nothing more.
+        const fragment = JSON.parse(readFileSync(ext.schemas.project, "utf8")) as JsonValue;
+        const properties = isJsonObject(fragment) ? fragment.properties : undefined;
+        fragmentProperties = isJsonObject(properties) ? properties : {};
       } catch {
         fragmentProperties = {};
       }
@@ -234,27 +238,34 @@ export function buildExtensionsPayload(registry: ExtensionRegistry): ExtensionsP
         studio: cls.studio,
       });
     }
-    payload.push({
+    const entry: ExtensionsPayloadEntry = {
       classes: ext.classes.map((cls) => {
-        const stateDefaults = cls.studio?.stateDefaults as Record<string, unknown> | undefined;
+        const stateDefaults = cls.studio?.stateDefaults;
         const isState =
           cls.project === null &&
           cls.server === null &&
           cls.connector === null &&
           cls.extensions.length === 0;
-        return {
-          name: cls.name,
-          path: cls.classPath,
-          ...(isState ? { state: true } : {}),
-          ...(stateDefaults && typeof stateDefaults === "object" ? { stateDefaults } : {}),
-        };
+        const payloadClass: ExtensionsPayloadClass = { name: cls.name, path: cls.classPath };
+        if (isState) {
+          payloadClass.state = true;
+        }
+        if (isJsonObject(stateDefaults)) {
+          payloadClass.stateDefaults = stateDefaults;
+        }
+        return payloadClass;
       }),
       contributions,
       name: ext.manifest.name,
       specifier: ext.specifier,
-      ...(ext.manifest.title === undefined ? {} : { title: ext.manifest.title }),
-      ...(ext.manifest.description === undefined ? {} : { description: ext.manifest.description }),
-    });
+    };
+    if (ext.manifest.title !== undefined) {
+      entry.title = ext.manifest.title;
+    }
+    if (ext.manifest.description !== undefined) {
+      entry.description = ext.manifest.description;
+    }
+    payload.push(entry);
   }
   return payload;
 }

package/src/site/headers-emitter.ts

@@ -24,6 +24,12 @@ export interface HeaderRule {
   headers: Record<string, string>;
 }
 
+/** The generated `_headers` stanzas, and the configuration problems found while deriving them. */
+export interface HeaderRuleSet {
+  rules: HeaderRule[];
+  errors: string[];
+}
+
 /**
  * The only content-addressed output the build produces. `variantFilename()` embeds an 8-character
  * digest of the source bytes, so a changed image is a changed URL and the old one can be cached
@@ -56,10 +62,7 @@ const AUTHOR_BANNER =
 export function buildHeaderRules(
   build: ProjectConfig["build"],
   cspSources?: CspSources,
-): {
-  rules: HeaderRule[];
-  errors: string[];
-} {
+): HeaderRuleSet {
   const cfg: HeadersConfig = build?.headers ?? {};
   const errors: string[] = [];
   if (cfg.enabled === false) {

package/src/site/i18n.ts

@@ -13,12 +13,9 @@
  */
 
 import { siteAbsoluteUrl } from "@jxsuite/schema/asset-paths";
-import {
-  canonicalizeLocale,
-  localeDirection,
-  localeOfRoute as localeForRoute,
-} from "@jxsuite/schema/locale";
+import { canonicalizeLocale, localeDirection, localeOfRoute } from "@jxsuite/schema/locale";
 import type { ResolvedI18n, TextDirection } from "@jxsuite/schema/locale";
+import type { TranslationMember } from "@jxsuite/site/context";
 
 import { servedRoute } from "./static-host.ts";
 
@@ -144,14 +141,6 @@ export interface LocaleAlternate {
   href: string;
 }
 
-/** One route in a translation set: the locale it serves, and where it lives. */
-export interface TranslationMember {
-  /** Canonical BCP 47 tag. */
-  locale: string;
-  /** Site-absolute route pattern, e.g. `/fr-ca/about/`. */
-  urlPattern: string;
-}
-
 /** A route as translation grouping sees it: its URL, and the key its document declared. */
 export interface TranslationRoute {
   /** From the document's `$translationKey`; absent when the key is derived from the path. */
@@ -169,6 +158,19 @@ export interface TranslationConflict {
   urlPatterns: string[];
 }
 
+/** Routes grouped into translation sets, and the collisions found while grouping them. */
+export interface TranslationSets {
+  conflicts: TranslationConflict[];
+  /** Keyed by `urlPattern`; members of one set share one array. */
+  sets: Map<string, TranslationMember[]>;
+}
+
+/** The `lang` a page ships with, and its `dir` when that is worth writing down. */
+export interface PageLanguage {
+  lang: string;
+  dir?: string;
+}
+
 /** Everything a page needs to know about its own locale, gathered once per build. */
 export interface PageLocaleContext {
   /** Absolute alternates for `<head>` and the sitemap; empty without a site `url`. */
@@ -198,13 +200,12 @@ export interface PageLocaleContext {
  *
  * @param {readonly TranslationRoute[]} routes - Concrete routes only
  * @param {ResolvedI18n | null} i18n
- * @returns {{ conflicts: TranslationConflict[]; sets: Map<string, TranslationMember[]> }} Sets are
- *   keyed by `urlPattern`; members of one set share one array
+ * @returns {TranslationSets} Sets are keyed by `urlPattern`; members of one set share one array
  */
 export function translationSets(
   routes: readonly TranslationRoute[],
   i18n: ResolvedI18n | null,
-): { conflicts: TranslationConflict[]; sets: Map<string, TranslationMember[]> } {
+): TranslationSets {
   const out = new Map<string, TranslationMember[]>();
   const conflicts: TranslationConflict[] = [];
   if (i18n === null) {
@@ -226,7 +227,7 @@ export function translationSets(
     if (route.translationKey !== undefined) {
       declared.add(route.urlPattern);
     }
-    const locale = localeForRoute(route.urlPattern, i18n);
+    const locale = localeOfRoute(route.urlPattern, i18n);
     if (locale === null) {
       continue;
     }
@@ -332,7 +333,7 @@ export function localeAlternates(
  * that says nothing.
  *
  * @param {object} args
- * @returns {{ lang: string; dir?: TextDirection | string }}
+ * @returns {PageLanguage}
  */
 export function pageLanguage({
   pageLang,
@@ -344,7 +345,7 @@ export function pageLanguage({
   pageDir?: string | undefined;
   routeLocale?: string | null;
   defaults?: { lang?: string | undefined; dir?: string | undefined } | undefined;
-}): { lang: string; dir?: string } {
+}): PageLanguage {
   const lang = pageLang ?? routeLocale ?? defaults?.lang ?? "en";
   const explicit = pageDir ?? defaults?.dir;
   if (explicit !== undefined) {

package/src/site/image-cache.ts

@@ -12,7 +12,7 @@ import { execSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { configHash, contentHash } from "./image-optimizer.ts";
 
-import type { ImageConfig, ImageManifest } from "./image-optimizer.ts";
+import type { ImageConfig, ImageManifest, ImageVariant } from "./image-optimizer.ts";
 
 interface CacheEntry {
   source: string; // Relative path to source image
@@ -20,6 +20,15 @@ interface CacheEntry {
   timestamp: number; // When the entry was cached
 }
 
+/**
+ * A cache entry as `manifest.json` may still hold it. A persisted cache outlives the build that
+ * wrote it, and an entry from before manifests carried `variants` has none, so pruning, which reads
+ * every entry rather than only the ones this build looked up, does not assume the list is there.
+ */
+interface PersistedEntry {
+  manifest: { variants?: readonly ImageVariant[] };
+}
+
 export interface CacheManifest {
   version: number; // Cache format version
   entries: Record<string, CacheEntry>; // Cached entries keyed by content+config hash
@@ -101,6 +110,9 @@ export function loadCache(projectRoot: string): CacheManifest {
     return { entries: {}, touched: new Set(), version: 1 };
   }
   try {
+    /* SAFETY: manifest.json is written only by saveCache, from a CacheManifest minus its
+       runtime-only `touched`, which is restored below; bytes that do not parse throw into the
+       empty-cache fallback. */
     const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
     parsed.touched = new Set();
     return parsed;
@@ -147,14 +159,15 @@ export function saveCache(
  */
 function pruneStale(cache: CacheManifest, touched: Set<string>) {
   const keep = new Set<string>();
-  for (const [key, entry] of Object.entries(cache.entries)) {
+  const entries = Object.entries<PersistedEntry>(cache.entries);
+  for (const [key, entry] of entries) {
     if (touched.has(key)) {
       for (const variant of entry.manifest.variants ?? []) {
         keep.add(variant.absolutePath);
       }
     }
   }
-  for (const [key, entry] of Object.entries(cache.entries)) {
+  for (const [key, entry] of entries) {
     if (touched.has(key)) {
       continue;
     }

package/src/site/image-optimizer.ts

@@ -68,7 +68,7 @@ async function getSharp() {
   // Production installs where @img/sharp-* native packages are adjacent to cli.js.
   try {
     const sharpMod = await import("sharp");
-    _sharp = sharpMod.default as SharpModule;
+    _sharp = sharpMod.default;
     return _sharp;
   } catch {
     // Fall through to CJS fallback below.
@@ -79,6 +79,7 @@ async function getSharp() {
   // Unreachable via the primary import path.
   try {
     const req = createRequire(resolve(process.cwd(), "package.json"));
+    // SAFETY: sharp's CommonJS entry is `module.exports = sharp`, the value its ESM default exports.
     _sharp = req("sharp") as SharpModule;
     return _sharp;
   } catch (error) {
@@ -91,6 +92,17 @@ async function getSharp() {
 
 const OPTIMIZED_DIR = "images/_optimized";
 
+/**
+ * The part of sharp's metadata this module reads, with every member optional. The sharp these types
+ * describe always reports all three, but `getSharp` may load the project's own copy instead, and
+ * sharp before 0.34 declared each of them optional.
+ */
+interface ReportedMetadata {
+  format?: string;
+  height?: number;
+  width?: number;
+}
+
 /**
  * Get image metadata (dimensions and format) via Sharp.
  *
@@ -99,9 +111,9 @@ const OPTIMIZED_DIR = "images/_optimized";
  */
 export async function getImageMetadata(srcPath: string) {
   const sharp = await getSharp();
-  const meta = await sharp(srcPath).metadata();
+  const meta: ReportedMetadata = await sharp(srcPath).metadata();
   return {
-    format: (meta.format ?? "unknown") as string,
+    format: meta.format ?? "unknown",
     height: meta.height ?? 0,
     width: meta.width ?? 0,
   };
@@ -216,7 +228,10 @@ export async function processImage(srcPath: string, cacheImgDir: string, config:
         continue;
       }
 
+      /* SAFETY: `format` is a free string from project config; a name outside the four keyed
+         qualities reads `undefined` from the lookup and takes the default of 80. */
       const quality = config.quality[format as keyof ImageConfig["quality"]] ?? 80;
+      // SAFETY: toFormat checks the name itself and throws for a format sharp cannot encode.
       const task = sharp(srcPath)
         .resize(width)
         .toFormat(format as SharpFormat, { quality })
@@ -248,7 +263,6 @@ export async function processImage(srcPath: string, cacheImgDir: string, config:
  */
 export function buildSrcset(variants: ImageVariant[], format: string) {
   return variants
-    .filter((v) => v.format === format)
-    .map((v) => `${v.outputPath} ${v.width}w`)
+    .flatMap((v) => (v.format === format ? [`${v.outputPath} ${v.width}w`] : []))
     .join(", ");
 }