@jxsuite/compiler 1.4.0 → 1.5.0

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,33 +96,39 @@ 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();
 
@@ -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/targets/compile-client.ts

@@ -16,21 +16,26 @@ import {
   DEFAULT_LIT_HTML_SRC,
   DEFAULT_REACTIVITY_SRC,
   buildAttrs,
+  childSeparator,
   colorSchemePrePaintScript,
   compileExpression,
   compileStatements,
   compileStyles,
   createCompileContext,
   emitFormulaFn,
+  emitRequestFetch,
   escapeHtml,
   isMutating,
   isRefObject,
   isSchemaOnly,
   isTemplateString,
+  PREFORMATTED_TAGS,
   pureSchemeOf,
   resolveStaticValue,
+  srcImportBinding,
 } from "../shared.ts";
 import {
+  bodyReturnsValue,
   hasStructuredBody,
   isExpandedSignal,
   isExpressionDef,
@@ -47,7 +52,6 @@ import type {
   JxDocument,
   JxMappedArray,
   JxMutableNode,
-  JxPrototypeDef,
   JxStyle,
 } from "@jxsuite/schema/types";
 
@@ -161,11 +165,11 @@ export function compileClient(
         if (!srcImportMap.has(def.$src)) {
           srcImportMap.set(def.$src, new Set());
         }
-        (srcImportMap.get(def.$src) as Set<string>).add(key);
+        (srcImportMap.get(def.$src) as Set<string>).add(srcImportBinding(key, def));
 
         // $src functions always produce computed entries (they return values)
         computedEntries.push([key, `() => { return ${key}(state); }`]);
-      } else if (typeof def.body === "string" && def.body.includes("return")) {
+      } else if (typeof def.body === "string" && bodyReturnsValue(def.body)) {
         // Body contains return → computed
         computedEntries.push([key, `() => { ${def.body} }`]);
       } else {
@@ -200,7 +204,7 @@ export function compileClient(
       // $prototype: "Request"
       if (def.$prototype === "Request") {
         stateEntries.push([key, null]);
-        initBlocks.push(emitRequestInit(key, def));
+        initBlocks.push(emitRequestFetch(key, def));
         continue;
       }
 
@@ -335,6 +339,8 @@ function buildClientNode(
   );
 
   const tag = def.tagName ?? "div";
+  // `white-space` inherits, so once inside a <pre> the whole subtree stays whitespace-significant.
+  nextContext.preformatted = context.preformatted === true || PREFORMATTED_TAGS.has(tag);
   const bindAttrs = [];
   let needsBind = false;
 
@@ -530,9 +536,14 @@ function buildClientNode(
     const listKey = `_children${counter.l}`;
     counter.l += 1;
     const childrenTpl = source.children
-      .map((c) => emitChildLit(c as JxMutableNode))
-      .join("\n      ");
-    bindings.set(listKey, `() => html\`\n      ${childrenTpl}\n    \``);
+      .map((c) => emitChildLit(c as JxMutableNode, nextContext.preformatted))
+      .join(childSeparator(nextContext.preformatted, "      "));
+    bindings.set(
+      listKey,
+      nextContext.preformatted
+        ? `() => html\`${childrenTpl}\``
+        : `() => html\`\n      ${childrenTpl}\n    \``,
+    );
     bindAttrs.push(`:render="${listKey}"`);
     needsBind = true;
     const bindAttrStr2 = ` ${bindAttrs.join(" ")}`;
@@ -551,7 +562,7 @@ function buildClientNode(
           counter,
         );
       })
-      .join("\n  ");
+      .join(childSeparator(nextContext.preformatted));
   }
 
   // Self-closing tags
@@ -570,13 +581,16 @@ function buildClientNode(
  * index.
  *
  * @param {JxMutableNode} def
+ * @param {boolean} [preformatted]
  * @returns {string}
  */
-function emitLitMapTemplate(def: JxMutableNode | undefined) {
+function emitLitMapTemplate(def: JxMutableNode | undefined, preformatted = false) {
   if (!def) {
     return "";
   }
   const tag = def.tagName ?? "div";
+  // `white-space` inherits, so once inside a <pre> the whole subtree stays whitespace-significant.
+  const inPre = preformatted || PREFORMATTED_TAGS.has(tag);
   let attrs = "";
 
   if (def.id) {
@@ -586,6 +600,20 @@ function emitLitMapTemplate(def: JxMutableNode | undefined) {
     attrs += ` class="${mapRefsToLit(def.className)}"`;
   }
 
+  // $props → lit property bindings. The element target emits these; the client target emitted
+  // Nothing, so a component in a list silently received none of its per-item props.
+  if (def.$props && typeof def.$props === "object") {
+    for (const [k, v] of Object.entries(def.$props)) {
+      if (isRefObject(v)) {
+        attrs += ` .${k}="\${${mapRefToClientExpr((v as { $ref: string }).$ref)}}"`;
+      } else if (typeof v === "string" && isTemplateString(v)) {
+        attrs += ` .${k}="${mapRefsToLit(v)}"`;
+      } else {
+        attrs += ` .${k}="\${${JSON.stringify(v)}}"`;
+      }
+    }
+  }
+
   // Attributes object
   if (def.attributes && typeof def.attributes === "object") {
     for (const [k, v] of Object.entries(def.attributes)) {
@@ -674,7 +702,8 @@ function emitLitMapTemplate(def: JxMutableNode | undefined) {
     // Legacy whole-children repeater nested inside a map template.
     inner = `\n      ${emitArrayHole(def.children)}\n    `;
   } else if (Array.isArray(def.children)) {
-    inner = `\n      ${def.children.map((c) => emitChildLit(c)).join("\n      ")}\n    `;
+    const rendered = def.children.map((c) => emitChildLit(c, inPre));
+    inner = inPre ? rendered.join("") : `\n      ${rendered.join("\n      ")}\n    `;
   }
 
   const voidTags = new Set(["input", "br", "hr", "img", "meta", "link"]);
@@ -689,9 +718,10 @@ function emitLitMapTemplate(def: JxMutableNode | undefined) {
  * via a `.map()` hole), or a nested element.
  *
  * @param {JxMutableNode | string} c
+ * @param {boolean} [preformatted]
  * @returns {string}
  */
-function emitChildLit(c: JxMutableNode | string): string {
+function emitChildLit(c: JxMutableNode | string, preformatted = false): string {
   if (typeof c === "string") {
     return isTemplateString(c) ? mapRefsToLit(c) : escapeHtml(c);
   }
@@ -701,7 +731,7 @@ function emitChildLit(c: JxMutableNode | string): string {
   if (isMappedArray(c)) {
     return emitArrayHole(c);
   }
-  return emitLitMapTemplate(c);
+  return emitLitMapTemplate(c, preformatted);
 }
 
 /**
@@ -888,61 +918,8 @@ function emitClientModule(
 }
 
 // ─── Prototype init emitters ─────────────────────────────────────────────────
-
-/**
- * @param {string} key
- * @param {JxMutableNode} def
- * @returns {string}
- */
-function emitRequestInit(key: string, def: JxPrototypeDef) {
-  const { url } = def;
-  const method = def.method ?? "GET";
-  const isTemplateUrl = isTemplateString(url);
-
-  if (def.manual) {
-    return `// ${key}: manual Request — fetch triggered by user action`;
-  }
-
-  const lines: string[] = [
-    `// ${key}: auto-fetch from ${isTemplateUrl ? "(dynamic URL)" : url}`,
-    "effect(() => {",
-  ];
-
-  if (isTemplateUrl) {
-    lines.push(
-      `  const url = \`${url}\`;`,
-      '  if (!url || url === "undefined" || url.includes("undefined")) return;',
-    );
-  } else {
-    lines.push(`  const url = ${JSON.stringify(url)};`);
-  }
-
-  const fetchOpts: string[] = [];
-  if (method !== "GET") {
-    fetchOpts.push(`method: ${JSON.stringify(method)}`);
-  }
-  if (def.headers) {
-    fetchOpts.push(`headers: ${JSON.stringify(def.headers)}`);
-  }
-  if (def.body) {
-    const bodyStr =
-      typeof def.body === "object"
-        ? JSON.stringify(JSON.stringify(def.body))
-        : JSON.stringify(def.body);
-    fetchOpts.push(`body: ${bodyStr}`);
-  }
-
-  const optsStr = fetchOpts.length > 0 ? `, { ${fetchOpts.join(", ")} }` : "";
-  lines.push(
-    `  fetch(url${optsStr})`,
-    "    .then(r => r.ok ? r.json() : Promise.reject(r.statusText))",
-    `    .then(d => { state.${key} = d; })`,
-    `    .catch(e => { state.${key} = { error: String(e) }; });`,
-    "});",
-  );
-
-  return lines.join("\n");
-}
+// Request auto-fetch lives in shared.ts (`emitRequestFetch`) so the element target emits the same
+// Effect against `this.state`.
 
 /**
  * @param {string} key
@@ -995,6 +972,25 @@ function emitCookieInit(key: string, cookieName: string, defaultVal: unknown) {
  * @param {string} ref
  * @returns {string}
  */
+/**
+ * Lower a `$ref` to the JS expression that reads it inside a map callback — the mirror of the
+ * element target's `refToExpr`/`mapRefToExpr`. Distinct from `refToBindingKey` below, which
+ * flattens `/` to `_` to name a binding and would produce nonsense (`state.$map_item`) as an
+ * expression.
+ *
+ * @param {string} ref
+ * @returns {string}
+ */
+function mapRefToClientExpr(ref: string) {
+  if (ref.startsWith("$map/")) {
+    return ref.slice("$map/".length).replaceAll("/", ".");
+  }
+  if (ref.startsWith("#/state/")) {
+    return `state.${ref.slice("#/state/".length).replaceAll("/", ".")}`;
+  }
+  return `state.${ref.replaceAll("/", ".")}`;
+}
+
 function refToBindingKey(ref: string) {
   if (ref.startsWith("#/state/")) {
     return ref.slice("#/state/".length).replaceAll("/", "_");