@jxsuite/compiler 5.1.2 → 6.0.1

package/src/site/asset-mounts.ts

@@ -20,8 +20,16 @@ import {
 } from "@jxsuite/schema/asset-paths";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
+import { errorMessage } from "@jxsuite/schema/parse";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
+/** What {@link copyMountedAssets} reports: files written, and URLs that resolved to nothing. */
+export interface MountedAssetCopy {
+  copied: number;
+  missing: string[];
+}
+
 /**
  * Gather every asset mount contributed by the project's extensions.
  *
@@ -45,31 +53,33 @@ export async function loadAssetMounts(
 
   for (const entry of registry.assetProviders()) {
     const sectionKey = entry.project?.key;
-    const sectionValue = sectionKey
-      ? (projectConfig as unknown as Record<string, unknown>)[sectionKey]
-      : undefined;
+    const sectionValue = sectionKey ? projectConfig[sectionKey] : undefined;
     if (
       sectionKey &&
       (sectionValue == null ||
-        (typeof sectionValue === "object" && Object.keys(sectionValue).length === 0))
+        (isNonNullObject(sectionValue) && Object.keys(sectionValue).length === 0))
     ) {
       continue;
     }
     try {
-      const declared = (await entry.call("assets", sectionValue ?? null, {
+      const declared = await entry.call("assets", sectionValue ?? null, {
         projectConfig,
         root: projectRoot,
-      })) as AssetMount[] | null;
+      });
+      /* The answer is extension code's, so each entry is checked before it is used: a hole, or a
+         mount missing its URL prefix or its directory, declares nothing. */
       for (const mount of declared ?? []) {
-        if (!mount?.urlPrefix || !mount.dir) {
+        if (!isNonNullObject(mount) || !mount.urlPrefix || !mount.dir) {
           continue;
         }
         const normalized: AssetMount = {
           dir: mount.dir,
           urlPrefix: normalizeAssetPrefix(mount.urlPrefix),
-          // What the owner says the mount may serve travels with it (a notes folder's `exclude`).
-          ...(typeof mount.filter === "function" && { filter: mount.filter }),
         };
+        // What the owner says the mount may serve travels with it (a notes folder's `exclude`).
+        if (isFunction(mount.filter)) {
+          normalized.filter = mount.filter;
+        }
         const prior = byPrefix.get(normalized.urlPrefix);
         if (prior) {
           if (prior.dir !== normalized.dir) {
@@ -84,7 +94,7 @@ export async function loadAssetMounts(
         mounts.push(normalized);
       }
     } catch (error) {
-      errors.push(`Error in ${entry.name}.assets: ${(error as Error).message}`);
+      errors.push(`Error in ${entry.name}.assets: ${errorMessage(error)}`);
     }
   }
 
@@ -113,13 +123,13 @@ export function collectAssetRefs(text: string, mounts: readonly AssetMount[], in
  * @param {Iterable<string>} urls - Mounted URLs collected from the compiled output
  * @param {readonly AssetMount[]} mounts
  * @param {string} outDir - Absolute build output directory
- * @returns {{ copied: number; missing: string[] }} Files written, and URLs that resolved to nothing
+ * @returns {MountedAssetCopy} Files written, and URLs that resolved to nothing
  */
 export function copyMountedAssets(
   urls: Iterable<string>,
   mounts: readonly AssetMount[],
   outDir: string,
-): { copied: number; missing: string[] } {
+): MountedAssetCopy {
   let copied = 0;
   const missing: string[] = [];
 

package/src/site/bundler.ts

@@ -16,7 +16,6 @@ import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { isNpmSpecifier, NPM_SPECIFIER_PREFIX } from "@jxsuite/schema/asset-paths";
-import type { BunPlugin } from "bun";
 
 /** Import specifiers left external in client bundles — provided by the page importmap. */
 export const CLIENT_EXTERNALS = ["@vue/reactivity", "lit-html"];
@@ -111,16 +110,28 @@ export interface BundleOptions {
   onFileLoaded?: (path: string) => void;
 }
 
+/**
+ * The part of a plugin builder the hooks use, typed so that both Bun's `PluginBuilder` and
+ * esbuild's `PluginBuild` are assignable to it: a plugin written against it is a plugin for either
+ * backend.
+ */
 interface PluginBuild {
   onResolve: (
     options: { filter: RegExp },
-    callback: (args: { path: string; importer: string }) => unknown,
+    callback: (args: { path: string; importer: string }) => ReturnType<BundleResolver["resolve"]>,
   ) => void;
-  onLoad: (options: { filter: RegExp }, callback: (args: { path: string }) => unknown) => void;
+  /** An `undefined` result hands the file back to the backend's own loader. */
+  onLoad: (options: { filter: RegExp }, callback: (args: { path: string }) => undefined) => void;
+}
+
+/** A plugin in the one shape both `Bun.build` and `esbuild.build` accept. */
+interface BundlePlugin {
+  name: string;
+  setup: (build: PluginBuild) => void;
 }
 
 /** Wrap the hooks as the one-plugin array both backends take. */
-function hookPlugins(opts: BundleOptions): NonNullable<Parameters<typeof Bun.build>[0]["plugins"]> {
+function hookPlugins(opts: BundleOptions): BundlePlugin[] {
   const { onFileLoaded, resolver } = opts;
   if (resolver === undefined && onFileLoaded === undefined) {
     return [];
@@ -136,7 +147,7 @@ function hookPlugins(opts: BundleOptions): NonNullable<Parameters<typeof Bun.bui
       });
     }
   };
-  return [{ name: "jx-bundle-hooks", setup } as unknown as BunPlugin];
+  return [{ name: "jx-bundle-hooks", setup }];
 }
 
 /**
@@ -184,6 +195,24 @@ function shouldMinify(opts: BundleOptions): boolean {
   return opts.minify ?? opts.target === "browser";
 }
 
+/** The resolution options both backends spell the same way, present only when they apply. */
+interface SharedResolution {
+  conditions?: string[];
+  define?: Record<string, string>;
+}
+
+/** Export conditions when the caller gave some, and {@link BROWSER_DEFINE} for browser bundles. */
+function sharedResolution(opts: BundleOptions): SharedResolution {
+  const shared: SharedResolution = {};
+  if (opts.conditions) {
+    shared.conditions = opts.conditions;
+  }
+  if (opts.target === "browser") {
+    shared.define = { ...BROWSER_DEFINE };
+  }
+  return shared;
+}
+
 /** Map a bundle target to esbuild's platform (conditions carry the workerd specifics). */
 function esbuildPlatform(target: BundleTargetName): "browser" | "node" {
   return target === "node" || target === "bun" ? "node" : "browser";
@@ -210,8 +239,7 @@ export async function bundleEntry(request: BundleRequest, opts: BundleOptions):
     const esbuild = await import("esbuild");
     await esbuild.build({
       bundle: true,
-      ...(opts.conditions ? { conditions: opts.conditions } : {}),
-      ...(opts.target === "browser" ? { define: { ...BROWSER_DEFINE } } : {}),
+      ...sharedResolution(opts),
       entryPoints: [request.entryPath],
       external,
       format: "esm",
@@ -219,14 +247,13 @@ export async function bundleEntry(request: BundleRequest, opts: BundleOptions):
       minify: shouldMinify(opts),
       outfile: request.outfile,
       platform: esbuildPlatform(opts.target),
-      plugins: plugins as unknown as NonNullable<Parameters<typeof esbuild.build>[0]["plugins"]>,
+      plugins,
     });
     return;
   }
 
   const result = await Bun.build({
-    ...(opts.conditions ? { conditions: opts.conditions } : {}),
-    ...(opts.target === "browser" ? { define: { ...BROWSER_DEFINE } } : {}),
+    ...sharedResolution(opts),
     entrypoints: [request.entryPath],
     external,
     format: "esm",
@@ -305,8 +332,7 @@ export async function bundleSource(
     const esbuild = await import("esbuild");
     await esbuild.build({
       bundle: true,
-      ...(opts.conditions ? { conditions: opts.conditions } : {}),
-      ...(opts.target === "browser" ? { define: { ...BROWSER_DEFINE } } : {}),
+      ...sharedResolution(opts),
       external: opts.external ?? [],
       format: "esm",
       logLevel: "silent",

package/src/site/client-runtime.ts

@@ -26,6 +26,9 @@ import {
   useNodeFallback,
 } from "./bundler.ts";
 import { DEFAULT_LIT_HTML_SRC, DEFAULT_REACTIVITY_SRC } from "../shared.ts";
+import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { errorMessage } from "@jxsuite/schema/parse";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 /** One import-map entry the build can satisfy itself. */
 interface RuntimeModule {
@@ -65,6 +68,12 @@ export function isPrefixSpecifier(specifier: string): boolean {
   return specifier.endsWith("/");
 }
 
+/** What a runtime write reports: files written, and the failures it carried on past. */
+export interface RuntimeWriteReport {
+  written: number;
+  errors: string[];
+}
+
 export interface ClientRuntime {
   /** The import map's `imports` object. */
   imports: Record<string, string>;
@@ -125,14 +134,14 @@ export function resolveClientRuntime(resolveDir: string = PACKAGE_DIR): ClientRu
  * @param {ClientRuntime} runtime
  * @param {string} outDir
  * @param {string} [resolveDir]
- * @returns {Promise<{ written: number; errors: string[] }>}
+ * @returns {Promise<RuntimeWriteReport>}
  */
 export async function writeClientRuntime(
   runtime: ClientRuntime,
   outDir: string,
   resolveDir: string = PACKAGE_DIR,
   minify = true,
-): Promise<{ written: number; errors: string[] }> {
+): Promise<RuntimeWriteReport> {
   const errors: string[] = [];
   let written = 0;
 
@@ -155,7 +164,7 @@ export async function writeClientRuntime(
       );
       written += 1;
     } catch (error) {
-      errors.push(`Bundling client runtime "${mod.specifier}": ${(error as Error).message}`);
+      errors.push(`Bundling client runtime "${mod.specifier}": ${errorMessage(error)}`);
     }
   }
   return { errors, written };
@@ -189,18 +198,21 @@ export function importMapAssets(imports: Record<string, string>): string[] {
 export function importMapAssetsInHtml(html: string): string[] {
   const found: string[] = [];
   for (const match of html.matchAll(/<script type="importmap">([\s\S]*?)<\/script>/g)) {
-    let imports: unknown;
+    let map: JsonValue;
     try {
-      ({ imports } = JSON.parse(match[1] as string) as { imports?: unknown });
+      /* SAFETY: capture group 1 is not optional in the pattern, so every match carries it, and
+         JSON.parse only ever yields JSON values; its `any` return type says nothing more. */
+      map = JSON.parse(match[1] as string) as JsonValue;
     } catch {
       // A map the build did not write and cannot parse names nothing this build must produce.
       continue;
     }
-    if (typeof imports !== "object" || imports === null) {
+    const imports = isJsonObject(map) ? map.imports : undefined;
+    if (!isNonNullObject(imports)) {
       continue;
     }
-    const entries = Object.entries(imports as Record<string, unknown>).filter(
-      (entry): entry is [string, string] => typeof entry[1] === "string",
+    const entries = Object.entries(imports).flatMap(([specifier, url]): [string, string][] =>
+      isString(url) ? [[specifier, url]] : [],
     );
     found.push(...importMapAssets(Object.fromEntries(entries)));
   }
@@ -224,10 +236,13 @@ export function renderImportMap(imports: Record<string, string>): string {
  */
 function canResolve(specifier: string, resolveDir: string): boolean {
   try {
+    // Both resolvers throw when the specifier does not resolve, and return its path when it does.
     if (useNodeFallback()) {
-      return typeof createRequire(join(resolveDir, "x.js")).resolve(specifier) === "string";
+      createRequire(join(resolveDir, "x.js")).resolve(specifier);
+    } else {
+      Bun.resolveSync(specifier, resolveDir);
     }
-    return typeof Bun.resolveSync(specifier, resolveDir) === "string";
+    return true;
   } catch {
     return false;
   }
@@ -264,13 +279,13 @@ const MAX_SUBPATH_PASSES = 10;
  * @param {string} outDir - Build output root
  * @param {string} [resolveDir] - Directory bare specifiers resolve from
  * @param {boolean} [minify] - Minify the emitted bundles (defaults to the browser-target default)
- * @returns {Promise<{ written: number; errors: string[] }>}
+ * @returns {Promise<RuntimeWriteReport>}
  */
 export async function writeRuntimeSubpaths(
   outDir: string,
   resolveDir: string = PACKAGE_DIR,
   minify = true,
-): Promise<{ written: number; errors: string[] }> {
+): Promise<RuntimeWriteReport> {
   const errors: string[] = [];
   const done = new Set<string>();
   /** Output path of a core re-export stub → the bare specifier it must re-export. */
@@ -293,6 +308,7 @@ export async function writeRuntimeSubpaths(
   /** `from "lit-html/directives/class-map.js"` — the import forms a bundler emits. */
   const importedSpecifiers = async (file: string): Promise<string[]> => {
     const text = readFileSync(file, "utf8");
+    // SAFETY: capture group 1 is not optional in the pattern, so every match carries it.
     return [...text.matchAll(/(?:from|import)\s*["']([^"']+)["']/g)].map((m) => m[1] as string);
   };
 
@@ -337,7 +353,7 @@ export async function writeRuntimeSubpaths(
           written += 1;
           discovered += 1;
         } catch (error) {
-          errors.push(`Bundling runtime subpath "${specifier}": ${(error as Error).message}`);
+          errors.push(`Bundling runtime subpath "${specifier}": ${errorMessage(error)}`);
         }
       }
     }
@@ -413,7 +429,7 @@ function finish(
   mirrors: Map<string, string>,
   errors: string[],
   written: number,
-): { written: number; errors: string[] } {
+): RuntimeWriteReport {
   let total = written;
   for (const [path, specifier] of mirrors) {
     if (existsSync(path)) {
@@ -424,9 +440,7 @@ function finish(
       writeFileSync(path, `export * from ${JSON.stringify(specifier)};\n`, "utf8");
       total += 1;
     } catch (error) {
-      errors.push(
-        `Writing shared core stub ${relative(outDir, path)}: ${(error as Error).message}`,
-      );
+      errors.push(`Writing shared core stub ${relative(outDir, path)}: ${errorMessage(error)}`);
     }
   }
   return { errors, written: total };

package/src/site/csp.ts

@@ -19,6 +19,16 @@
 import { createHash } from "node:crypto";
 import type { CspConfig, HeadersConfig } from "@jxsuite/schema/types";
 
+/**
+ * The headers a policy adds: the policy itself under its enforcing or report-only name, and the
+ * endpoint group its `report-to` names when reporting is on.
+ */
+export interface CspHeaders {
+  "Content-Security-Policy"?: string;
+  "Content-Security-Policy-Report-Only"?: string;
+  "Reporting-Endpoints"?: string;
+}
+
 /** Everything a page contributed to the policy. Accumulated across the whole build. */
 export interface CspSources {
   /** `'sha256-…'` for each distinct inline script. */
@@ -59,10 +69,9 @@ const FONT_EXTENSION = /\.(woff2?|ttf|otf|eot)(\?|#|$)/i;
 
 /** Read one double- or single-quoted attribute out of a raw tag attribute string. */
 function attr(attrs: string, name: string): string | undefined {
-  return new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i")
-    .exec(attrs)
-    ?.slice(2)
-    .find((v) => v !== undefined);
+  // Group 2 is the double-quoted value and group 3 the single-quoted one; only one participates.
+  const match = new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i").exec(attrs);
+  return match?.[2] ?? match?.[3];
 }
 
 /** The origin of an absolute http(s) URL, or null for anything relative, `data:` or malformed. */
@@ -176,12 +185,13 @@ export function normalizeCspConfig(security: HeadersConfig["security"]): CspConf
  *
  * @param {CspSources} sources
  * @param {CspConfig} config
- * @returns {Record<string, string>}
+ * @returns {CspHeaders}
  */
-export function buildCspHeaders(sources: CspSources, config: CspConfig): Record<string, string> {
+export function buildCspHeaders(sources: CspSources, config: CspConfig): CspHeaders {
   const list = (fixed: string[], origins: Set<string>) => [...fixed, ...origins].join(" ");
 
-  const directives: Record<string, string | false> = {
+  // The computed directives, in the same shape as the overrides `config.directives` merges in.
+  const directives: NonNullable<CspConfig["directives"]> = {
     "base-uri": "'self'",
     "default-src": "'self'",
     "font-src": list(["'self'"], sources.fontOrigins),
@@ -212,11 +222,10 @@ export function buildCspHeaders(sources: CspSources, config: CspConfig): Record<
     .map(([name, value]) => `${name} ${String(value)}`)
     .join("; ");
 
-  const headerName =
+  const headers: CspHeaders =
     config.mode === "report-only"
-      ? "Content-Security-Policy-Report-Only"
-      : "Content-Security-Policy";
-  const headers: Record<string, string> = { [headerName]: policy };
+      ? { "Content-Security-Policy-Report-Only": policy }
+      : { "Content-Security-Policy": policy };
   if (config.reportUri !== undefined && config.reportUri !== "") {
     headers["Reporting-Endpoints"] = `csp-endpoint="${config.reportUri}"`;
   }

package/src/site/db-push.ts

@@ -14,13 +14,13 @@ import { resolve } from "node:path";
 import { applyBindingFragments } from "@jxsuite/create/scaffold";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
-import type { FormatEntry } from "@jxsuite/schema/format-registry";
+import type { DataPushRequest, FormatEntry } from "@jxsuite/schema/format-registry";
+import { isJsonObject } from "@jxsuite/schema/guards";
+import type { JsonObject } from "@jxsuite/schema/types";
 
-export interface DbPushOptions {
-  dryRun?: boolean;
-  /** Restrict the push to one connection name. */
-  connection?: string;
-}
+/* `jx db push` takes the same request as the Studio data-push route, so the shape is declared once
+   in @jxsuite/schema; `DbPushOptions` stays this module's public name for it. */
+export type { DataPushRequest as DbPushOptions } from "@jxsuite/schema/format-registry";
 
 export interface ConnectionPushResult {
   connection: string;
@@ -38,6 +38,10 @@ export interface DbPushResult {
   wranglerPath: string | null;
 }
 
+/**
+ * How a push reads a connector's `deploySchema` answer (`DeploySchemaResult`): every member
+ * optional, and defaulted where it is read.
+ */
 interface DeployResultLike {
   statements?: string[];
   warnings?: string[];
@@ -48,19 +52,19 @@ interface DeployResultLike {
  * Push the project's table schemas to their connections' databases.
  *
  * @param {string} projectRoot - Absolute path to the project directory
- * @param {DbPushOptions} [options]
+ * @param {DataPushRequest} [options]
  * @returns {Promise<DbPushResult>}
  */
 export async function dbPush(
   projectRoot: string,
-  options: DbPushOptions = {},
+  options: DataPushRequest = {},
 ): Promise<DbPushResult> {
   const { dryRun = false, connection: only } = options;
   const { config } = loadProjectConfig(projectRoot);
   const registry = await buildProjectExtensionRegistry(projectRoot, config);
 
-  const connections = (config.connections ?? {}) as Record<string, Record<string, unknown>>;
-  const tables = (config.data ?? {}) as Record<string, { connection?: string }>;
+  const connections = isJsonObject(config.connections) ? config.connections : {};
+  const tables = isJsonObject(config.data) ? config.data : {};
 
   const names = Object.keys(connections).filter((name) => !only || name === only);
   if (only && names.length === 0) {
@@ -73,16 +77,20 @@ export async function dbPush(
     );
   }
 
-  const env: Record<string, unknown> = {
+  const env: NodeJS.ProcessEnv = {
     ...process.env,
     ...readDevVars(projectRoot),
     JX_PROJECT_ROOT: projectRoot,
   };
 
   const results: ConnectionPushResult[] = [];
-  const fragments: Record<string, unknown>[] = [];
+  const fragments: JsonObject[] = [];
   for (const name of names) {
-    const connection: Record<string, unknown> = { ...connections[name], $name: name };
+    const declared = connections[name];
+    // An entry that is not an object declares no provider, so it fails the lookup just below.
+    const connection: JsonObject = isJsonObject(declared)
+      ? { ...declared, $name: name }
+      : { $name: name };
     const provider = String(connection.provider ?? "");
     const entry = connectorByProvider(registry.connectors(), provider);
     if (!entry) {
@@ -91,17 +99,21 @@ export async function dbPush(
           `it (enable the extension in project.json "extensions")`,
       );
     }
-    const connectionTables: Record<string, unknown> = {};
+    const connectionTables: Record<string, JsonObject> = {};
     for (const [tableName, def] of Object.entries(tables)) {
-      if (def.connection === name) {
+      if (isJsonObject(def) && def.connection === name) {
         connectionTables[tableName] = def;
       }
     }
 
-    const deployed = (await entry.call("deploySchema", connectionTables, connection, {
-      dryRun,
-      env,
-    })) as DeployResultLike;
+    /* A connector's `deploySchema` answers `{ statements, applied, warnings }` (extensions.md §8);
+       this push reads each member as optional and defaults it where it is read. */
+    const deployed: DeployResultLike = await entry.call(
+      "deploySchema",
+      connectionTables,
+      connection,
+      { dryRun, env },
+    );
     results.push({
       applied: deployed.applied ?? !dryRun,
       connection: name,
@@ -112,8 +124,9 @@ export async function dbPush(
     });
 
     if (entry.capabilities.bindings) {
-      const fragment = (await entry.call("bindings", connection)) as Record<string, unknown>;
-      if (fragment && Object.keys(fragment).length > 0) {
+      // A connector's `bindings` answers with a wrangler config fragment (extensions.md §8).
+      const fragment = await entry.call("bindings", connection);
+      if (isJsonObject(fragment) && Object.keys(fragment).length > 0) {
         fragments.push(fragment);
       }
     }
@@ -152,7 +165,8 @@ export function readDevVars(projectRoot: string): Record<string, string> {
   if (!existsSync(path)) {
     return {};
   }
-  const out: Record<string, string> = {};
+  // A later line for the same key replaces an earlier one.
+  const vars = new Map<string, string>();
   for (const rawLine of readFileSync(path, "utf8").split("\n")) {
     const line = rawLine.trim();
     if (line === "" || line.startsWith("#")) {
@@ -171,8 +185,8 @@ export function readDevVars(projectRoot: string): Record<string, string> {
       value = value.slice(1, -1);
     }
     if (key !== "") {
-      out[key] = value;
+      vars.set(key, value);
     }
   }
-  return out;
+  return Object.fromEntries(vars);
 }

package/src/site/dev-command.ts

@@ -36,8 +36,8 @@ export function resolveDevEntry(projectRoot: string): string {
 
 /** The slice of `process` runDev touches — injectable for tests. */
 export interface ProcessLike {
-  on: (event: string, handler: () => void) => unknown;
-  exitCode?: number | string | undefined;
+  on: (event: string, handler: () => void) => void;
+  exitCode?: number | string | null | undefined;
 }
 
 /**
@@ -53,7 +53,7 @@ export function runDev(
   projectRoot: string,
   port: number | undefined,
   spawnImpl: typeof spawn = spawn,
-  proc: ProcessLike = process as unknown as ProcessLike,
+  proc: ProcessLike = process,
 ): ChildProcess {
   const entry = resolveDevEntry(projectRoot);
   const args = [entry, "--root", projectRoot];