@jxsuite/compiler 1.4.0 → 2.0.0

package/src/site/site-loader.ts

@@ -48,6 +48,7 @@ const DEFAULTS = {
     formats: ["webp", "avif"],
     lazyLoad: true,
     optimize: true,
+    picture: true,
     quality: { avif: 65, jpeg: 80, png: 80, webp: 80 },
     service: "build",
     sizes: "(max-width: 768px) 100vw, 50vw",

package/src/site/validate-command.ts

@@ -3,9 +3,11 @@
  *
  * Extends the original project.json check into the full compliance walk:
  *
- * 1. `project.json` against the generated entry schema (validateProjectFile);
- * 2. The committed entry documents are SELF-CONTAINED (no residual relative `$ref`s — the
- *    editor-resolution guarantee of the bundled form, specs/extensions.md §5.4);
+ * 1. The committed entry documents are SELF-CONTAINED and SINGLE-RESOURCE: every `$ref` is a
+ *    root-relative JSON Pointer that resolves inside the file — the editor-resolution guarantee of
+ *    the committed form (specs/extensions.md §5.4). Checked first and fatal, since walks 2–4
+ *    compile those documents;
+ * 2. `project.json` against the generated entry schema (validateProjectFile);
  * 3. Every document under `components/`, `pages/`, and `layouts/` against the bundled document schema
  *    (core + extension `$paths` union — the same schema the studio consumes);
  * 4. Every project-local `*.class.json` against the generated class schema;
@@ -94,38 +96,44 @@ export async function validateProjectTree(
   const issues: ProjectTreeIssue[] = [];
   let checked = 0;
 
-  // 1. project.json against the generated entry schema.
-  const projectResult = await validateProjectFile(root);
-  checked += 1;
-  if (!projectResult.valid) {
-    issues.push({ errors: projectResult.errors ?? [], file: "project.json" });
-  }
-
-  // 2. Committed entry documents must be self-contained (the editor-resolution guarantee).
+  /* 1. Committed entry documents must be self-contained (the editor-resolution guarantee). This
+     runs FIRST because every later walk compiles one of them: an unresolvable ref surfaces from ajv
+     as a thrown MissingRefError, so diagnosing it here turns a stack trace into "regenerate with
+     `jx schema`". Nothing downstream is meaningful until it holds, hence the early return. */
   for (const name of ["project.schema.json", "document.schema.json"]) {
     const path = resolve(root, name);
     if (!existsSync(path)) {
       continue;
     }
     checked += 1;
-    const residual: string[] = [];
-    collectRelativeRefs(JSON.parse(readFileSync(path, "utf8")), residual);
-    if (residual.length > 0) {
+    const entry = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const unresolvable = collectUnresolvableRefs(entry);
+    if (unresolvable.length > 0) {
       issues.push({
-        errors: residual.map((ref) => ({
+        errors: unresolvable.map(({ reason, ref }) => ({
           message:
-            `relative $ref "${ref}" — committed entry documents must be self-contained; ` +
-            `regenerate with \`jx schema\``,
+            `$ref "${ref}" ${reason} — committed entry documents must be self-contained ` +
+            `single-resource schemas; regenerate with \`jx schema\``,
         })),
         file: name,
       });
     }
   }
+  if (issues.length > 0) {
+    return { checked, issues, valid: false };
+  }
+
+  // 2. project.json against the generated entry schema.
+  const projectResult = await validateProjectFile(root);
+  checked += 1;
+  if (!projectResult.valid) {
+    issues.push({ errors: projectResult.errors ?? [], file: "project.json" });
+  }
 
   const { addFormats, Ajv } = await loadAjv();
 
   // 3. Documents against the bundled document schema (the same schema the studio consumes).
-  const { document: documentSchema } = await readBundledProjectSchemas(root);
+  const { document: documentSchema } = await readBundledProjectSchemas(root, { write: false });
   const docAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(docAjv);
   const validateDoc = docAjv.compile(documentSchema);
@@ -186,30 +194,118 @@ export async function validateProjectTree(
   return { checked, issues, valid: issues.length === 0 };
 }
 
-/** Collect relative-path `$ref`s (anything without a URI scheme that isn't a `#` pointer). */
-function collectRelativeRefs(node: unknown, out: string[]): void {
-  if (Array.isArray(node)) {
-    for (const item of node) {
-      collectRelativeRefs(item, out);
+/**
+ * Every `$ref` a committed entry document may carry must be a root-relative JSON Pointer that
+ * resolves inside the same file. Three ways that fails, all of which break editor resolution: a
+ * relative path (needs Node module resolution), a URI (VS Code fetches it over the network instead
+ * of matching an embedded `$id`), and a pointer with no node at the other end.
+ *
+ * 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
+ * @returns {{ ref: string; reason: string }[]} One entry per offending `$ref`
+ */
+function collectUnresolvableRefs(
+  entry: Record<string, unknown>,
+): { ref: string; reason: string }[] {
+  const out: { ref: string; reason: string }[] = [];
+  const seen = new Set<Record<string, unknown>>();
+
+  const resolvePointer = (pointer: string): boolean => {
+    let current: unknown = 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) {
+        return false;
+      }
+      current = (current as Record<string, unknown>)[segment];
+      if (current === undefined) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+  const walk = (node: unknown): void => {
+    if (!isRecord(node) || seen.has(node)) {
+      return;
     }
-    return;
-  }
-  if (node === null || typeof node !== "object") {
-    return;
-  }
-  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
-    if (
-      key === "$ref" &&
-      typeof value === "string" &&
-      !value.startsWith("#") &&
-      !/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value)
-    ) {
-      out.push(value);
+    seen.add(node);
+    const ref = node.$ref;
+    if (typeof ref === "string") {
+      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("#")) {
+        out.push({ reason: "is a relative path only Node module resolution can follow", ref });
+      } else if (ref.length > 1 && !ref.startsWith("#/")) {
+        out.push({ reason: "is an $anchor reference, which has no root-pointer form", ref });
+      } else if (ref.length > 1 && !resolvePointer(ref.slice(1))) {
+        out.push({ reason: "points at no node in this document", ref });
+      }
     }
-    collectRelativeRefs(value, out);
-  }
+    for (const [keyword, value] of Object.entries(node)) {
+      if (!SUBSCHEMA_KEYWORDS.has(keyword)) {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          walk(item);
+        }
+      } else if (isRecord(value)) {
+        // Map-valued keywords hold subschemas one level down; single-valued ones are the schema.
+        walk(value);
+        if (MAP_SUBSCHEMA_KEYWORDS.has(keyword)) {
+          for (const item of Object.values(value)) {
+            walk(item);
+          }
+        }
+      }
+    }
+  };
+  walk(entry);
+  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",
+  "definitions",
+  "dependencies",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+]);
+
+/** Every keyword position a subschema can occupy (see {@link MAP_SUBSCHEMA_KEYWORDS} for maps). */
+const SUBSCHEMA_KEYWORDS = new Set([
+  ...MAP_SUBSCHEMA_KEYWORDS,
+  "additionalItems",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "oneOf",
+  "prefixItems",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+]);
+
 /** Recursively list `.json` files under a directory (absent directories yield nothing). */
 function walkJsonFiles(dir: string): string[] {
   if (!existsSync(dir)) {

package/src/site/well-known.ts

@@ -0,0 +1,221 @@
+/**
+ * Two files a site is expected to publish and nothing generates: `manifest.webmanifest` and
+ * `.well-known/security.txt`.
+ *
+ * Both are pure functions of `project.json` plus what the build already knows about the site, which
+ * is the reason they belong here rather than in `public/` — an author copying either between
+ * projects also copies the values that were right for the other one.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { canonicalizeLocale } from "@jxsuite/schema/locale";
+import type { ManifestConfig, ProjectConfig, SecurityTxtConfig } from "@jxsuite/schema/types";
+
+/** The two sizes a browser wants before it will offer to install a site. */
+const INSTALL_ICON_SIZES = [192, 512];
+
+export interface GeneratedFile {
+  /** Path relative to `outDir`. */
+  path: string;
+  content: string;
+}
+
+export interface WellKnownOutput {
+  files: GeneratedFile[];
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Build `manifest.webmanifest` from the `manifest` section, falling back to what the project
+ * already says about itself.
+ *
+ * `name` and `start_url` are not asked for twice: a project has a `name`, and `start_url` is the
+ * site root unless the author says otherwise. Everything else is theirs.
+ *
+ * @param {ProjectConfig} projectConfig
+ * @returns {WellKnownOutput}
+ */
+export function buildManifest(projectConfig: ProjectConfig): WellKnownOutput {
+  const config: ManifestConfig | undefined = projectConfig.manifest;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (config === undefined || config.enabled === false) {
+    return { errors, files: [], warnings };
+  }
+
+  const name = config.name ?? projectConfig.name ?? "Jx Site";
+  const icons = config.icons ?? [];
+  const manifest: Record<string, unknown> = {
+    display: config.display ?? "standalone",
+    icons,
+    name,
+    short_name: config.shortName ?? name,
+    start_url: 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: 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 }),
+  };
+
+  /*
+   * A warning, not an error. The manifest is valid and useful without these — it still supplies
+   * the name and theme colour a browser shows — but a site cannot be *installed* without an icon
+   * at each size, and that is the whole reason most people add one.
+   */
+  const declared = new Set(
+    icons.flatMap((icon) =>
+      (icon.sizes ?? "").split(/\s+/).map((size) => Math.trunc(Number(size.split("x")[0]))),
+    ),
+  );
+  const missing = INSTALL_ICON_SIZES.filter((size) => !declared.has(size));
+  if (missing.length > 0) {
+    warnings.push(
+      `manifest: no ${missing.join("px and no ")}px icon declared — browsers will not offer to ` +
+        "install the site without one at each size.",
+    );
+  }
+
+  return {
+    errors,
+    files: [{ content: `${JSON.stringify(manifest, null, 2)}\n`, path: "manifest.webmanifest" }],
+    warnings,
+  };
+}
+
+/** The `<head>` entries a generated manifest needs to be found and to look right when installed. */
+export function manifestHeadEntries(
+  projectConfig: ProjectConfig,
+): { tagName: string; attributes: Record<string, string> }[] {
+  const config = projectConfig.manifest;
+  if (config === undefined || config.enabled === false) {
+    return [];
+  }
+  const entries: { tagName: string; attributes: Record<string, string> }[] = [
+    { attributes: { href: "/manifest.webmanifest", rel: "manifest" }, tagName: "link" },
+  ];
+  if (config.themeColor !== undefined) {
+    entries.push({
+      attributes: { content: config.themeColor, name: "theme-color" },
+      tagName: "meta",
+    });
+  }
+  return entries;
+}
+
+/**
+ * Build `.well-known/security.txt` (RFC 9116).
+ *
+ * `.well-known` only. §3 makes that the canonical location, and a second copy at the root is a
+ * second thing to forget to update.
+ *
+ * @param {ProjectConfig} projectConfig
+ * @param {Date} now - Evaluated against `Expires`; injected so the check is testable
+ * @returns {WellKnownOutput}
+ */
+export function buildSecurityTxt(projectConfig: ProjectConfig, now: Date): WellKnownOutput {
+  const config: SecurityTxtConfig | undefined = projectConfig.securityTxt;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (config === undefined || config.enabled === false) {
+    return { errors, files: [], warnings };
+  }
+
+  const contact = config.contact ?? [];
+  if (contact.length === 0) {
+    errors.push("securityTxt: at least one `contact` is required (RFC 9116 §2.5.3).");
+  }
+
+  /*
+   * `Expires` is required by §2.5.5, and it is the field everyone forgets. A past date is worse
+   * than a missing file: it advertises a reporting channel while telling the reporter the
+   * information is stale, so both cases fail the build rather than emitting something misleading.
+   */
+  if (config.expires === undefined) {
+    errors.push(
+      "securityTxt: `expires` is required (RFC 9116 §2.5.5) — a security.txt with no expiry " +
+        "never goes stale visibly, which is how they end up pointing at people who left.",
+    );
+  } else {
+    const expires = new Date(config.expires);
+    if (Number.isNaN(expires.getTime())) {
+      errors.push(`securityTxt: \`expires\` is not a valid date: "${config.expires}".`);
+    } else if (expires.getTime() <= now.getTime()) {
+      errors.push(
+        `securityTxt: \`expires\` is in the past (${expires.toISOString()}) — an expired ` +
+          "security.txt tells a reporter not to trust what it says.",
+      );
+    }
+  }
+
+  const languages: string[] = [];
+  for (const tag of config.preferredLanguages ?? []) {
+    const canonical = canonicalizeLocale(tag);
+    if (canonical === null) {
+      errors.push(`securityTxt.preferredLanguages: "${tag}" is not a well-formed language tag.`);
+    } else {
+      languages.push(canonical);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { errors, files: [], warnings };
+  }
+
+  const lines: string[] = [
+    "# Generated by @jxsuite/compiler — configure via securityTxt in project.json.",
+    ...contact.map((value) => `Contact: ${value}`),
+    `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}`),
+    ...(languages.length > 0 ? [`Preferred-Languages: ${languages.join(", ")}`] : []),
+    ...(config.canonical === undefined ? [] : [`Canonical: ${config.canonical}`]),
+    ...(config.policy ?? []).map((value) => `Policy: ${value}`),
+    ...(config.hiring ?? []).map((value) => `Hiring: ${value}`),
+  ];
+
+  return {
+    errors,
+    files: [{ content: `${lines.join("\n")}\n`, path: ".well-known/security.txt" }],
+    warnings,
+  };
+}
+
+/**
+ * Write generated files under `outDir`, skipping any the author already supplied.
+ *
+ * The skip is the point: `public/.well-known/security.txt` is copied before this runs, and a
+ * hand-placed file there is how an author ships a **clearsigned** one — which needs a private key
+ * at build time and is therefore not something the build can do. Deferring costs zero code.
+ *
+ * @param {readonly GeneratedFile[]} files
+ * @param {string} outDir
+ * @param {(path: string) => boolean} exists
+ * @returns {{ written: number; skipped: string[] }}
+ */
+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) {
+    const target = join(outDir, file.path);
+    if (exists(target)) {
+      skipped.push(file.path);
+      continue;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content, "utf8");
+    written += 1;
+  }
+  return { skipped, written };
+}