@jxsuite/compiler 5.1.2 → 6.0.1

package/src/site/site-loader.ts

@@ -6,7 +6,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import type { ImageConfig, ProjectConfig } from "@jxsuite/schema/types";
+import type { ImageConfig, JxDocumentValue, ProjectConfig } from "@jxsuite/schema/types";
 import { errorMessage, parseProjectConfig } from "@jxsuite/schema/parse";
 import { resolve } from "node:path";
 
@@ -24,9 +24,10 @@ export interface ResolvedProjectConfig extends ProjectConfig {
     adapter?: string;
     outDir: string;
     format: string;
-    trailingSlash: string;
+    /** `null` when project.json writes it so explicitly: the merge below keeps an author's null. */
+    trailingSlash: string | null;
     provider?: string | null;
-    [key: string]: unknown;
+    [key: string]: JxDocumentValue | undefined;
   };
 }
 
@@ -92,6 +93,8 @@ export function loadProjectConfig(projectRoot: string) {
     build: { ...DEFAULTS.build, ...raw.build },
     defaults: { ...DEFAULTS.defaults, ...raw.defaults },
     images: { ...DEFAULTS.images, ...raw.images },
+    // An explicit JSON `null` url means no site URL, which every consumer reads as "".
+    url: raw.url ?? DEFAULTS.url,
   };
 
   // Preserve arrays and objects that shouldn't be shallow-merged

package/src/site/static-host.ts

@@ -40,10 +40,10 @@ export function isNotFoundRoute(urlPattern: string): boolean {
  * `/` either way, and any other setting leaves the route as written.
  *
  * @param {string} urlPattern - A concrete route (`/about`, `/kb/a/b`)
- * @param {string} [trailingSlash] - `build.trailingSlash`
+ * @param {string | null} [trailingSlash] - `build.trailingSlash`
  * @returns {string} The route as the host serves it
  */
-export function servedRoute(urlPattern: string, trailingSlash?: string): string {
+export function servedRoute(urlPattern: string, trailingSlash?: string | null): string {
   if (urlPattern === "/") {
     return "/";
   }
@@ -93,7 +93,7 @@ export function htmlDeclaresNoindex(html: string): boolean {
 }
 
 /** The `<head>` of a built page, or the whole string when it has no closing tag. */
-function headOf(html: string): { head: string; end: number } {
+function headOf(html: string) {
   const end = html.search(/<\/head\s*>/i);
   return { end, head: end === -1 ? html : html.slice(0, end) };
 }

package/src/site/validate-command.ts

@@ -26,7 +26,8 @@ import { findA11yDefects } from "@jxsuite/schema/a11y";
 import { findDialogDefects } from "@jxsuite/schema/dialogs";
 import { findPopoverDefects, overlayScopeFor } from "@jxsuite/schema/overlays";
 import type { OverlayScope } from "@jxsuite/schema/overlays";
-import type { JxElement } from "@jxsuite/schema/types";
+import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, JxElement } from "@jxsuite/schema/types";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import { readBundledProjectSchemas } from "./schema-command.ts";
@@ -88,12 +89,14 @@ export interface ProjectTreeValidationResult {
 
 // Minimal structural types for the optional `ajv` dependency (same pattern as validate-project).
 interface AjvValidateFn {
-  (doc: unknown): boolean;
+  (doc: JsonValue): boolean;
   errors?: unknown[] | null;
 }
+/** What `compile` receives: parsed JSON, or the class schema generateClassSchema builds in memory. */
+type AjvSchemaInput = JsonValue | ReturnType<typeof generateClassSchema>;
 interface AjvInstance {
-  compile: (schema: unknown) => AjvValidateFn;
-  addSchema: (schema: unknown) => AjvInstance;
+  compile: (schema: AjvSchemaInput) => AjvValidateFn;
+  addSchema: (schema: JsonValue) => AjvInstance;
 }
 type AjvCtor = new (opts: {
   allErrors: boolean;
@@ -104,8 +107,18 @@ type AddFormatsFn = (ajv: AjvInstance) => void;
 
 async function loadAjv(): Promise<{ Ajv: AjvCtor; addFormats: AddFormatsFn }> {
   try {
-    // The schemas are JSON Schema 2020-12, so use the matching Ajv build.
-    const { default: Ajv } = (await import("ajv/dist/2020")) as unknown as { default: AjvCtor };
+    /*
+     * The schemas are JSON Schema 2020-12, so use the matching Ajv build.
+     * SAFETY: the default export of `ajv/dist/2020` is the Ajv2020 class. AjvCtor restates, in
+     * JSON terms, only the three constructor options, `compile`, `addSchema` and the validate
+     * function's call and `errors` used below; ajv reports a schema value it cannot use as a thrown
+     * error.
+     */
+    const { default: Ajv } = (await import("ajv/dist/2020")) as { default: AjvCtor };
+    /*
+     * SAFETY: ajv-formats' default export is the plugin function that takes an Ajv instance and
+     * registers the formats on it; AddFormatsFn states only that call.
+     */
     // @ts-expect-error — resolved through @jxsuite/schema's dependency
     const { default: addFormats } = (await import("ajv-formats")) as { default: AddFormatsFn };
     return { addFormats, Ajv };
@@ -141,7 +154,7 @@ export async function validateProjectTree(
       continue;
     }
     checked += 1;
-    const entry = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const entry = readJson(path);
     const unresolvable = collectUnresolvableRefs(entry);
     if (unresolvable.length > 0) {
       issues.push({
@@ -180,6 +193,12 @@ export async function validateProjectTree(
   const scope = overlayScopeFor(
     walkClassFiles(root).flatMap((file) => {
       try {
+        /*
+         * SAFETY: not schema-checked here; the class-schema pass below reports a malformed
+         * definition. overlayScopeFor tolerates any parsed JSON in this slot: it skips `null`,
+         * reads `tagName` through isString (a primitive or array has none, so it is skipped), and
+         * reads `observedAttributes` through Array.isArray.
+         */
         return [JSON.parse(readFileSync(file, "utf8")) as JxElement];
       } catch {
         // A malformed definition is reported by the class-schema pass below, not here.
@@ -193,9 +212,13 @@ export async function validateProjectTree(
         continue; // Validated against the class schema below.
       }
       checked += 1;
-      const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+      const doc = readJson(file);
       if (validateDoc(doc)) {
-        // Only a well-formed document is judged; a schema error is the report for the rest.
+        /*
+         * Only a well-formed document is judged; a schema error is the report for the rest.
+         * SAFETY: validateDoc just accepted `doc` against the bundled document schema, which is
+         * the JSON Schema rendering of JxElement.
+         */
         lint.push(...lintDocument(doc as JxElement, relative(root, file), scope));
       } else {
         issues.push({ errors: validateDoc.errors ?? [], file: relative(root, file) });
@@ -209,7 +232,7 @@ export async function validateProjectTree(
   const validateClass = classAjv.compile(generateClassSchema());
   for (const file of walkClassFiles(root)) {
     checked += 1;
-    const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+    const doc = readJson(file);
     if (!validateClass(doc)) {
       issues.push({ errors: validateClass.errors ?? [], file: relative(root, file) });
     }
@@ -230,11 +253,10 @@ export async function validateProjectTree(
       addFormats(fragAjv);
       for (const specifier of SHIPPED_RESOURCE_SPECIFIERS) {
         const resourcePath = selfRequire.resolve(specifier);
-        const resource = JSON.parse(readFileSync(resourcePath, "utf8")) as Record<string, unknown>;
-        fragAjv.addSchema(resource);
+        fragAjv.addSchema(readJson(resourcePath));
       }
       try {
-        fragAjv.compile(JSON.parse(readFileSync(fragmentPath, "utf8")));
+        fragAjv.compile(readJson(fragmentPath));
       } catch (error) {
         issues.push({
           errors: [{ message: error instanceof Error ? error.message : String(error) }],
@@ -248,6 +270,14 @@ export async function validateProjectTree(
   return { checked, issues, lint, valid: issues.length === 0 && !fatalLint };
 }
 
+/**
+ * Read and parse a JSON file. `JSON.parse` without a reviver only ever produces JSON values, so the
+ * declared type is exact; what shape of JSON it is stays for the caller to check.
+ */
+function readJson(path: string): JsonValue {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
 /** The three lints over one document, as findings that name their file. */
 function lintDocument(doc: JxElement, file: string, scope: OverlayScope): ProjectTreeLintFinding[] {
   const findings: ProjectTreeLintFinding[] = [];
@@ -300,26 +330,29 @@ export function formatProjectTreeLint(result: ProjectTreeValidationResult): stri
  * Walks only subschema keyword positions, since `examples`/`default`/`const`/`enum` hold instance
  * data and Jx document examples legitimately contain `$ref` strings of their own.
  *
- * @param {Record<string, unknown>} entry - Parsed committed entry document
+ * @param {JsonValue} entry - Parsed committed entry document
  * @returns {{ ref: string; reason: string }[]} One entry per offending `$ref`
  */
-function collectUnresolvableRefs(
-  entry: Record<string, unknown>,
-): { ref: string; reason: string }[] {
+function collectUnresolvableRefs(entry: JsonValue): { ref: string; reason: string }[] {
   const out: { ref: string; reason: string }[] = [];
-  const seen = new Set<Record<string, unknown>>();
+  const seen = new Set<JsonObject>();
 
   const resolvePointer = (pointer: string): boolean => {
-    let current: unknown = entry;
+    let current: JsonValue | undefined = entry;
     for (const raw of pointer.slice(1).split("/")) {
       if (raw === "") {
         continue;
       }
       const segment = raw.replaceAll("~1", "/").replaceAll("~0", "~");
-      if (typeof current !== "object" || current === null) {
+      if (!isNonNullObject(current)) {
         return false;
       }
-      current = (current as Record<string, unknown>)[segment];
+      /*
+       * SAFETY: `current` is a JSON object or array. Both are read by string key here, exactly as
+       * the original property access did (an array segment such as "0" is a string key too); the
+       * result is only compared with `undefined`, so JsonObject merely types the lookup.
+       */
+      current = (current as JsonObject)[segment];
       if (current === undefined) {
         return false;
       }
@@ -327,13 +360,13 @@ function collectUnresolvableRefs(
     return true;
   };
 
-  const walk = (node: unknown): void => {
-    if (!isRecord(node) || seen.has(node)) {
+  const walk = (node: JsonValue): void => {
+    if (!isJsonObject(node) || seen.has(node)) {
       return;
     }
     seen.add(node);
     const ref = node.$ref;
-    if (typeof ref === "string") {
+    if (isString(ref)) {
       if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(ref)) {
         out.push({ reason: "is an absolute URI editors resolve over the network", ref });
       } else if (!ref.startsWith("#")) {
@@ -352,7 +385,7 @@ function collectUnresolvableRefs(
         for (const item of value) {
           walk(item);
         }
-      } else if (isRecord(value)) {
+      } else if (isJsonObject(value)) {
         // Map-valued keywords hold subschemas one level down; single-valued ones are the schema.
         walk(value);
         if (MAP_SUBSCHEMA_KEYWORDS.has(keyword)) {
@@ -367,11 +400,6 @@ function collectUnresolvableRefs(
   return out;
 }
 
-/** True for a plain object (a candidate subschema node). */
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Keywords whose values map names to subschemas. */
 const MAP_SUBSCHEMA_KEYWORDS = new Set([
   "$defs",
@@ -446,10 +474,12 @@ export function formatProjectTreeIssues(result: ProjectTreeValidationResult): st
   for (const issue of result.issues) {
     lines.push(`${issue.file}:`);
     for (const error of issue.errors) {
-      const { instancePath, message } = (error ?? {}) as {
-        instancePath?: string;
-        message?: string;
-      };
+      /*
+       * An ajv error object or a `{ message }` record. Destructuring a primitive, an array or a
+       * null slot (via `{}`) yields neither member, so the fallback covers every non-object.
+       */
+      const fields: JsonObject = isJsonObject(error) ? error : {};
+      const { instancePath, message } = fields;
       lines.push(`  - ${instancePath || "/"}: ${message ?? JSON.stringify(error)}`);
     }
   }

package/src/site/well-known.ts

@@ -13,6 +13,7 @@ import { siteBasePath, withBase } from "@jxsuite/schema/asset-paths";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { canonicalizeLocale } from "@jxsuite/schema/locale";
+import { isString } from "@jxsuite/schema/guards";
 import type { ManifestConfig, ProjectConfig, SecurityTxtConfig } from "@jxsuite/schema/types";
 
 /** The two sizes a browser wants before it will offer to install a site. */
@@ -24,6 +25,42 @@ export interface GeneratedFile {
   content: string;
 }
 
+type ManifestIcon = NonNullable<ManifestConfig["icons"]>[number];
+
+/**
+ * The emitted `manifest.webmanifest`, member names as the W3C Web App Manifest spells them. Members
+ * are assigned in this order, which is the order they serialize in.
+ */
+interface WebAppManifest {
+  display: NonNullable<ManifestConfig["display"]>;
+  icons: ManifestIcon[];
+  name: string;
+  short_name: string;
+  start_url: string;
+  description?: string;
+  theme_color?: string;
+  background_color?: string;
+  scope?: string;
+  orientation?: string;
+  lang?: string;
+  dir?: NonNullable<ManifestConfig["dir"]>;
+  categories?: string[];
+}
+
+/**
+ * Add an optional manifest member only when the project set it, so an unset one is omitted rather
+ * than serialized. Members land in call order, which is the order they serialize in.
+ */
+function setIfDefined<K extends keyof WebAppManifest>(
+  manifest: WebAppManifest,
+  key: K,
+  value: WebAppManifest[K] | undefined,
+): void {
+  if (value !== undefined) {
+    manifest[key] = value;
+  }
+}
+
 export interface WellKnownOutput {
   files: GeneratedFile[];
   errors: string[];
@@ -56,25 +93,29 @@ export function buildManifest(projectConfig: ProjectConfig): WellKnownOutput {
    * `start_url` at the old root just opens the wrong page from the home screen.
    */
   const base = siteBasePath(projectConfig.url);
-  const icons = [];
+  const icons: ManifestIcon[] = [];
   for (const icon of config.icons ?? []) {
-    icons.push(typeof icon.src === "string" ? { ...icon, src: withBase(base, icon.src) } : icon);
+    icons.push(isString(icon.src) ? { ...icon, src: withBase(base, icon.src) } : icon);
   }
-  const manifest: Record<string, unknown> = {
+  const manifest: WebAppManifest = {
     display: config.display ?? "standalone",
     icons,
     name,
     short_name: config.shortName ?? name,
     start_url: withBase(base, config.startUrl ?? "/"),
-    ...(config.description === undefined ? {} : { description: config.description }),
-    ...(config.themeColor === undefined ? {} : { theme_color: config.themeColor }),
-    ...(config.backgroundColor === undefined ? {} : { background_color: config.backgroundColor }),
-    ...(config.scope === undefined ? {} : { scope: withBase(base, config.scope) }),
-    ...(config.orientation === undefined ? {} : { orientation: config.orientation }),
-    ...(config.lang === undefined ? {} : { lang: config.lang }),
-    ...(config.dir === undefined ? {} : { dir: config.dir }),
-    ...(config.categories === undefined ? {} : { categories: config.categories }),
   };
+  setIfDefined(manifest, "description", config.description);
+  setIfDefined(manifest, "theme_color", config.themeColor);
+  setIfDefined(manifest, "background_color", config.backgroundColor);
+  setIfDefined(
+    manifest,
+    "scope",
+    config.scope === undefined ? undefined : withBase(base, config.scope),
+  );
+  setIfDefined(manifest, "orientation", config.orientation);
+  setIfDefined(manifest, "lang", config.lang);
+  setIfDefined(manifest, "dir", config.dir);
+  setIfDefined(manifest, "categories", config.categories);
 
   /*
    * A warning, not an error. The manifest is valid and useful without these — it still supplies
@@ -183,6 +224,10 @@ export function buildSecurityTxt(projectConfig: ProjectConfig, now: Date): WellK
   const lines: string[] = [
     "# Generated by @jxsuite/compiler — configure via securityTxt in project.json.",
     ...contact.map((value) => `Contact: ${value}`),
+    /*
+     * SAFETY: `config.expires === undefined` pushed an error above, and any error returned before
+     * this point, so `expires` is a string here.
+     */
     `Expires: ${new Date(config.expires as string).toISOString().replace(/\.\d{3}Z$/, "Z")}`,
     ...(config.encryption ?? []).map((value) => `Encryption: ${value}`),
     ...(config.acknowledgments ?? []).map((value) => `Acknowledgments: ${value}`),
@@ -215,7 +260,7 @@ export function writeWellKnown(
   files: readonly GeneratedFile[],
   outDir: string,
   exists: (path: string) => boolean,
-): { written: number; skipped: string[] } {
+) {
   let written = 0;
   const skipped: string[] = [];
   for (const file of files) {

package/src/targets/compile-class.ts

@@ -8,18 +8,19 @@
 import type {
   JxClassCtorDef,
   JxClassDef,
+  JxClassDefs,
   JxClassMethodDef,
   JxClassParamDef,
 } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
 
 /**
  * Compile a .class.json schema to a JavaScript ES module string.
  *
  * @param {JxClassDef} classDef - Parsed .class.json content (must have $prototype: "Class")
- * @param {Record<string, unknown>} [_opts]
  * @returns {string} JavaScript module source code
  */
-export function compileClassJson(classDef: JxClassDef, _opts: Record<string, unknown> = {}) {
+export function compileClassJson(classDef: JxClassDef) {
   const className = classDef.title;
   if (!className) {
     throw new Error("compileClassJson: missing title (class name)");
@@ -30,7 +31,7 @@ export function compileClassJson(classDef: JxClassDef, _opts: Record<string, unk
   const fields = defs?.fields ?? {};
   // JSON objects inherit Object.prototype.constructor — only an own object value counts.
   const rawCtor = defs?.constructor;
-  const ctor = typeof rawCtor === "object" ? rawCtor : undefined;
+  const ctor = isOwnCtorDef(rawCtor) ? rawCtor : undefined;
   const methods = defs?.methods ?? {};
 
   const lines: string[] = [
@@ -153,6 +154,17 @@ export function compileClassJson(classDef: JxClassDef, _opts: Record<string, unk
   return lines.join("\n");
 }
 
+/**
+ * Whether a `$defs.constructor` read is the document's own constructor definition rather than the
+ * `Object.prototype.constructor` function every JSON object inherits.
+ *
+ * @param {JxClassDefs["constructor"]} value
+ * @returns {boolean}
+ */
+function isOwnCtorDef(value: JxClassDefs["constructor"]): value is JxClassCtorDef {
+  return typeof value === "object";
+}
+
 /**
  * Resolve the base class name from an extends value.
  *
@@ -163,7 +175,7 @@ function resolveBaseClass(ext: JxClassDef["extends"]) {
   if (!ext) {
     return "Object";
   }
-  if (typeof ext === "string") {
+  if (isString(ext)) {
     return ext;
   }
   if (ext.$ref) {
@@ -186,7 +198,7 @@ function resolveParams(params: JxClassParamDef[]) {
         return param.$ref.split("/").pop();
       }
       const name = param.identifier ?? param.name;
-      return typeof name === "string" ? name : "arg";
+      return isString(name) ? name : "arg";
     })
     .join(", ");
 }