@jxsuite/compiler 8.2.0 → 8.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -52,10 +52,10 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/create": "^1.5.4",
-    "@jxsuite/runtime": "^6.1.0",
-    "@jxsuite/schema": "^5.2.0",
-    "@jxsuite/site": "^2.3.1",
+    "@jxsuite/create": "^1.5.5",
+    "@jxsuite/runtime": "^6.2.0",
+    "@jxsuite/schema": "^5.3.0",
+    "@jxsuite/site": "^2.4.0",
     "@vue/reactivity": "3.5.44",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
@@ -63,8 +63,8 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/connector": "^0.8.4",
-    "@jxsuite/parser": "^4.3.0",
+    "@jxsuite/connector": "^0.8.5",
+    "@jxsuite/parser": "^4.3.1",
     "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4"
   }

package/src/cli.ts

@@ -29,6 +29,7 @@ Commands:
   preview [root]   Serve an already-built dist/ directory
   schema [root]    Generate project.schema.json + document.schema.json from project.json#/extensions
   validate [root]  Validate the whole project: project.json, documents, classes, and fragments
+  convert <paths…> Move documents between .json and .jxn, repairing every reference to them
   db push [root]   Sync the data section's tables to their connections (additive-only)
 
 Options:
@@ -38,10 +39,24 @@ Options:
   --port <n>     dev/preview: port to listen on (default 3000 / 4173)
   --dry-run      db push: print the statements without executing them
   --connection   db push: restrict to one connection name
-  --strict       validate: fail on an overlay or accessibility lint error, not only a schema error`);
+  --strict       validate: fail on an overlay or accessibility lint error, not only a schema error
+  --to <format>  convert: jxn or json
+  --drop-comments convert: convert a .jxn file to .json even though it has comments`);
     process.exit(0);
   }
 
+  // Its positionals are paths and not a project root, so it does not join the split below.
+  if (command === "convert") {
+    try {
+      const { runConvert } = await import("./site/convert-command.ts");
+      runConvert(process.cwd(), args.slice(1));
+    } catch (error) {
+      console.error(errorMessage(error));
+      process.exit(1);
+    }
+    return;
+  }
+
   // `db push` is a two-word command; normalize it before the flag/positional split.
   const isDb = command === "db";
   const dbSubcommand = isDb ? args[1] : null;

package/src/compiler.ts

@@ -27,7 +27,7 @@ import { emitElementModule } from "./targets/compile-element.ts";
 import { compileStaticPage } from "./targets/compile-static.ts";
 import { compileClient } from "./targets/compile-client.ts";
 import { isClassDef, isString } from "@jxsuite/schema/guards";
-import { parseJxDocument } from "@jxsuite/schema/parse";
+import { isNativeDocumentPath, parseNativeDocument } from "@jxsuite/schema/jxn";
 import type { JxDocument, JxStyle } from "@jxsuite/schema/types";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 
@@ -94,8 +94,8 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   let raw: JxDocument;
   if (isString(sourcePath)) {
     const source = readFileSync(sourcePath, "utf8");
-    if (sourcePath.endsWith(".json")) {
-      raw = parseJxDocument(source, sourcePath);
+    if (isNativeDocumentPath(sourcePath)) {
+      raw = parseNativeDocument(source, sourcePath);
     } else {
       const { extname } = await import("node:path");
       const ext = extname(sourcePath).toLowerCase();

package/src/site/convert-command.ts

@@ -0,0 +1,59 @@
+/**
+ * Convert command: `jx convert` resolves the project's `@jxsuite/server/convert` and runs it under
+ * Bun, as `jx dev` does and for the same reasons. The compiler cannot depend on the server, and the
+ * refactor pass that repairs references ships as TypeScript this Node entry cannot load.
+ *
+ * @module convert-command
+ */
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { ProcessLike } from "./dev-command.ts";
+
+/**
+ * Resolve the project's converter.
+ *
+ * @param projectRoot Absolute project root.
+ * @throws {Error} When the server package is not installed.
+ */
+export function resolveConvertEntry(projectRoot: string): string {
+  try {
+    return createRequire(join(projectRoot, "package.json")).resolve("@jxsuite/server/convert");
+  } catch {
+    throw new Error(
+      `@jxsuite/server is not installed in ${projectRoot}. ` +
+        `Add it to devDependencies (e.g. \`bun add -d @jxsuite/server\`) and retry.`,
+    );
+  }
+}
+
+/**
+ * Spawn the converter under Bun.
+ *
+ * @param projectRoot Absolute project root.
+ * @param argv The arguments after the command.
+ * @param spawnImpl Injectable for tests.
+ * @param proc Injectable for tests.
+ */
+export function runConvert(
+  projectRoot: string,
+  argv: readonly string[],
+  spawnImpl: typeof spawn = spawn,
+  proc: ProcessLike = process,
+): ChildProcess {
+  const entry = resolveConvertEntry(projectRoot);
+  const child = spawnImpl("bun", [entry, "--root", projectRoot, ...argv], { stdio: "inherit" });
+  child.on("error", (error: NodeJS.ErrnoException) => {
+    console.error(
+      error.code === "ENOENT"
+        ? "jx convert runs on Bun, which was not found on your PATH. Install it from https://bun.sh and retry."
+        : `Failed to start jx convert: ${error.message}`,
+    );
+    proc.exitCode = 1;
+  });
+  child.on("exit", (code) => {
+    proc.exitCode = code ?? 0;
+  });
+  return child;
+}

package/src/site/format-host.ts

@@ -20,6 +20,7 @@ import type {
 } from "@jxsuite/schema/format-registry";
 import { isJsonObject } from "@jxsuite/schema/guards";
 import type { JsonObject, JsonValue, ProjectConfig } from "@jxsuite/schema/types";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 export type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registry";
@@ -133,7 +134,7 @@ export async function buildProjectExtensionRegistry(
   return buildExtensionRegistry(
     projectConfig?.extensions,
     createNodeFormatIO(projectRoot),
-    resolve(projectRoot, "project.json"),
+    projectFilePath(projectRoot),
   );
 }
 
@@ -176,7 +177,7 @@ export async function buildInstalledExtensionRegistry(
   const registry = await buildExtensionRegistry(
     present,
     createNodeFormatIO(projectRoot),
-    resolve(projectRoot, "project.json"),
+    projectFilePath(projectRoot),
   );
   return { missing, registry };
 }

package/src/site/layout-resolver.ts

@@ -9,7 +9,8 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { errorMessage, parseJxDocument } from "@jxsuite/schema/parse";
+import { parseNativeDocument } from "@jxsuite/schema/jxn";
+import { errorMessage } from "@jxsuite/schema/parse";
 import { resolve } from "node:path";
 import { resolveLayout as resolveLayoutWith } from "@jxsuite/site/layout";
 import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
@@ -26,9 +27,9 @@ export function nodeLayoutLoader(projectRoot: string): (layoutRef: string) => Jx
       throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
     }
     try {
-      return parseJxDocument(readFileSync(layoutPath, "utf8"), layoutPath);
+      return parseNativeDocument(readFileSync(layoutPath, "utf8"), layoutPath);
     } catch (error) {
-      throw new Error(`Invalid layout JSON at ${layoutPath}: ${errorMessage(error)}`, {
+      throw new Error(`Invalid layout at ${layoutPath}: ${errorMessage(error)}`, {
         cause: error,
       });
     }

package/src/site/pages-discovery.ts

@@ -18,7 +18,8 @@
 
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { isJsonObject, isString } from "@jxsuite/schema/guards";
-import { errorMessage, parseJxDocument } from "@jxsuite/schema/parse";
+import { isNativeDocumentPath, parseNativeDocument } from "@jxsuite/schema/jxn";
+import { errorMessage } from "@jxsuite/schema/parse";
 import { compareRoutes, fileToRoute as routeFromFileName } from "@jxsuite/site/routes";
 import { pageCount, pageSlice, pageUrl, pagedSource, pagination } from "@jxsuite/site/pagination";
 import type { PagePagination, PagedSource } from "@jxsuite/site/pagination";
@@ -80,8 +81,8 @@ export async function readPageDocument(
   registry?: FormatRegistry,
 ): Promise<JxDocument> {
   const source = readFileSync(filePath, "utf8");
-  if (filePath.endsWith(".json")) {
-    return parseJxDocument(source, filePath);
+  if (isNativeDocumentPath(filePath)) {
+    return parseNativeDocument(source, filePath);
   }
   const ext = extname(filePath).toLowerCase();
   const entry = registry?.byExtension(ext, "parse");
@@ -200,7 +201,11 @@ async function declaredTranslationKey(
  */
 export async function discoverPages(pagesDir: string, registry?: FormatRegistry) {
   const routes: Route[] = [];
-  const pageExtensions = new Set([".json", ...(registry?.documentExtensions("page") ?? [])]);
+  const pageExtensions = new Set([
+    ".json",
+    ".jxn",
+    ...(registry?.documentExtensions("page") ?? []),
+  ]);
   await walkDir(pagesDir, pagesDir, routes, pageExtensions, registry);
 
   // Static routes first, then dynamic, then catch-all (spec §4.4) — the shared ordering.

package/src/site/schema-command.ts

@@ -29,6 +29,7 @@ import { loadProjectConfig } from "./site-loader.ts";
 import type { ExtensionInfo } from "@jxsuite/schema/extension-registry";
 import type { SchemaJsonLoader } from "@jxsuite/schema/project-schemas";
 import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 const CORE_PROJECT_SPECIFIER = "@jxsuite/schema/schemas/project.core.schema.json";
 const CORE_DOCUMENT_SPECIFIER = "@jxsuite/schema/schema.json";
@@ -95,7 +96,7 @@ export async function readBundledProjectSchemas(
 ) {
   const { write = true } = options;
   const root = resolve(projectRoot);
-  const projectJsonPath = resolve(root, "project.json");
+  const projectJsonPath = projectFilePath(root);
   const projectSchemaPath = resolve(root, "project.schema.json");
   const documentSchemaPath = resolve(root, "document.schema.json");
 

package/src/site/site-build.ts

@@ -160,6 +160,7 @@ import type {
 } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { CacheManifest } from "./image-cache.js";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 declare module "@jxsuite/schema/format-registry" {
   /**
@@ -463,9 +464,12 @@ export async function buildSite(
   if (existsSync(componentsDir)) {
     log("Compiling components...");
     const componentExtensions = [".json", ...formatRegistry.documentExtensions("component")];
-    const componentFiles = readdirSync(componentsDir).filter((f: string) =>
-      componentExtensions.some((ext) => f.endsWith(ext)),
-    );
+    /* Sorted, because this order is the order of the sheets in every page's `<head>`, and readdir
+       has none of its own: on ext4 it follows a hash of the name, so the same project built to
+       different bytes on different machines. */
+    const componentFiles = readdirSync(componentsDir)
+      .filter((f: string) => componentExtensions.some((ext) => f.endsWith(ext)))
+      .toSorted();
     const componentOutDir = resolve(outDir, "components");
     mkdirSync(componentOutDir, { recursive: true });
 
@@ -505,7 +509,7 @@ export async function buildSite(
           resolveElementPath: (refPath: string, currentDir: string | null) => {
             const depPath = currentDir ? resolve(currentDir, refPath) : resolve(refPath);
             const depTag = componentTagByPath.get(depPath);
-            return depTag ? `./${depTag}.js` : refPath.replace(/\.json$/, ".js");
+            return depTag ? `./${depTag}.js` : refPath.replace(/\.(?:json|jxn)$/i, ".js");
           },
           rewriteSrc: (specifier: string, docDir: string | null) =>
             withBase(componentBase, rewriteSidecarSrc(specifier, docDir)),
@@ -602,7 +606,7 @@ export async function buildSite(
         /* SAFETY: `ProjectConfig.state` is a plain record of state entries, and the collector reads
            only a document's `state`, so a document carrying that one member is all it needs. */
         { state: projectConfig.state } as JxElement,
-        resolve(projectRoot, "project.json"),
+        projectFilePath(projectRoot),
         projectRoot,
       ),
     );

package/src/site/site-loader.ts

@@ -9,6 +9,7 @@ import { existsSync, readFileSync } from "node:fs";
 import type { ImageConfig, JxDocumentValue, ProjectConfig } from "@jxsuite/schema/types";
 import { errorMessage, parseProjectConfig } from "@jxsuite/schema/parse";
 import { resolve } from "node:path";
+import { projectFilePath } from "@jxsuite/schema/project-file/node";
 
 /**
  * Default project configuration. All properties are optional in project.json; these defaults fill
@@ -71,7 +72,7 @@ const DEFAULTS = {
  * @throws {Error} If project.json is missing or invalid JSON
  */
 export function loadProjectConfig(projectRoot: string) {
-  const configPath = resolve(projectRoot, "project.json");
+  const configPath = projectFilePath(projectRoot);
 
   if (!existsSync(configPath)) {
     throw new Error(`project.json not found in ${projectRoot}`);

package/src/site/validate-command.ts

@@ -18,6 +18,8 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isJxnPath, isNativeDocumentPath, lintJxn, parseJxn } from "@jxsuite/schema/jxn";
+import { errorMessage } from "@jxsuite/schema/parse";
 import { createRequire } from "node:module";
 import { join, relative, resolve } from "node:path";
 import { generateClassSchema } from "@jxsuite/schema";
@@ -31,6 +33,7 @@ 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";
+import { PROJECT_FILE_NAME } from "@jxsuite/schema/project-file";
 
 /** Directories that hold Jx documents validated against the document schema. */
 const DOCUMENT_DIRS = ["components", "pages", "layouts"] as const;
@@ -63,8 +66,8 @@ export interface ProjectTreeLintFinding {
   file: string;
   /** The node's path inside the document. */
   path: (string | number)[];
-  /** Which lint: `popover`, `dialog` or `accessibility`. */
-  source: "popover" | "dialog" | "accessibility";
+  /** Which lint: `popover`, `dialog`, `accessibility`, or `notation` for a `.jxn` file's text. */
+  source: "popover" | "dialog" | "accessibility" | "notation";
   rule: string;
   message: string;
   detail: string;
@@ -175,7 +178,7 @@ export async function validateProjectTree(
   const projectResult = await validateProjectFile(root);
   checked += 1;
   if (!projectResult.valid) {
-    issues.push({ errors: projectResult.errors ?? [], file: "project.json" });
+    issues.push({ errors: projectResult.errors ?? [], file: PROJECT_FILE_NAME });
   }
 
   const { addFormats, Ajv } = await loadAjv();
@@ -212,7 +215,13 @@ export async function validateProjectTree(
         continue; // Validated against the class schema below.
       }
       checked += 1;
-      const doc = readJson(file);
+      const read = readDocumentFile(file, relative(root, file));
+      lint.push(...read.warnings);
+      if (read.failure !== null) {
+        issues.push(read.failure);
+        continue;
+      }
+      const doc = read.document;
       if (validateDoc(doc)) {
         /*
          * Only a well-formed document is judged; a schema error is the report for the rest.
@@ -270,6 +279,49 @@ export async function validateProjectTree(
   return { checked, issues, lint, valid: issues.length === 0 && !fatalLint };
 }
 
+/** A document file as the validator takes it: its value, or why it has none. */
+interface ReadDocumentFile {
+  document: JsonValue;
+  failure: ProjectTreeIssue | null;
+  warnings: ProjectTreeLintFinding[];
+}
+
+/**
+ * Read a document file for checking. A `.jxn` file that does not read is a finding with a line and
+ * column, and not a stack trace, and an escape that changes what its code means is reported whether
+ * or not the rest of the file reads.
+ */
+function readDocumentFile(file: string, name: string): ReadDocumentFile {
+  if (!isJxnPath(file)) {
+    return { document: readJson(file), failure: null, warnings: [] };
+  }
+  const text = readFileSync(file, "utf8");
+  const warnings = lintJxn(text).map((warning): ProjectTreeLintFinding => ({
+    detail: warning.message,
+    file: name,
+    message: `line ${warning.line}, column ${warning.column}: ${warning.message}`,
+    path: [],
+    rule: "escape",
+    severity: "warn",
+    source: "notation",
+  }));
+  try {
+    return { document: readJxnValue(text), failure: null, warnings };
+  } catch (error) {
+    return {
+      document: null,
+      failure: { errors: [{ message: errorMessage(error) }], file: name },
+      warnings,
+    };
+  }
+}
+
+/** A `.jxn` file's document, as the JSON value it is. */
+function readJxnValue(text: string): JsonValue {
+  const document = parseJxn(text);
+  return isJsonObject(document) ? document : null;
+}
+
 /**
  * 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.
@@ -431,7 +483,7 @@ const SUBSCHEMA_KEYWORDS = new Set([
   "unevaluatedProperties",
 ]);
 
-/** Recursively list `.json` files under a directory (absent directories yield nothing). */
+/** Recursively list document files under a directory (absent directories yield nothing). */
 function walkJsonFiles(dir: string): string[] {
   if (!existsSync(dir)) {
     return [];
@@ -441,7 +493,7 @@ function walkJsonFiles(dir: string): string[] {
     const path = join(dir, name);
     if (statSync(path).isDirectory()) {
       out.push(...walkJsonFiles(path));
-    } else if (name.endsWith(".json")) {
+    } else if (isNativeDocumentPath(name)) {
       out.push(path);
     }
   }

package/src/targets/compile-element.ts

@@ -49,7 +49,7 @@ import {
   isTagExpression,
   paramNames,
 } from "@jxsuite/schema/guards";
-import { parseJxDocument } from "@jxsuite/schema/parse";
+import { isNativeDocumentPath, parseNativeDocument } from "@jxsuite/schema/jxn";
 import { resolveShadowMode } from "../shadow.ts";
 import type { ShadowMode } from "../shadow.ts";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
@@ -132,8 +132,8 @@ export async function compileElement(
         return;
       }
       visited.add(filePath);
-      if (filePath.endsWith(".json")) {
-        doc = parseJxDocument(readFileSync(filePath, "utf8"), filePath);
+      if (isNativeDocumentPath(filePath)) {
+        doc = parseNativeDocument(readFileSync(filePath, "utf8"), filePath);
       } else {
         const { extname } = await import("node:path");
         const ext = extname(filePath).toLowerCase();
@@ -179,7 +179,7 @@ export async function compileElement(
         /** @type {string} */
         const importPath = resolveElementPath
           ? resolveElementPath(refPath, currentDir)
-          : refPath.replace(/\.json$/, ".js");
+          : refPath.replace(/\.(?:json|jxn)$/i, ".js");
         elementImports.push(importPath);
       }
     }
@@ -197,7 +197,7 @@ export async function compileElement(
       resolveShadowMode(doc, opts.defaults),
       opts.serverBaseUrl,
     );
-    const outputPath = filePath ? filePath.replace(/\.json$/, ".js") : `${tagName}.js`;
+    const outputPath = filePath ? filePath.replace(/\.(?:json|jxn)$/i, ".js") : `${tagName}.js`;
     files.push({ content: jsContent, path: outputPath, tagName });
   }