@jxsuite/server 8.7.0 → 9.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/server",
-  "version": "8.7.0",
+  "version": "9.0.0",
   "description": "Jx development server with live reload, server-side proxy, and studio integration",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,7 @@
     ".": "./src/server.ts",
     "./dev": "./src/dev.ts",
     "./convert": "./src/convert.ts",
+    "./format": "./src/format.ts",
     "./ai-api": "./src/ai-api.ts",
     "./data": "./src/data-api.ts",
     "./import-api": "./src/import-api.ts",
@@ -55,18 +56,18 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/ai": "^0.43.4",
-    "@jxsuite/catalog": "^0.1.12",
-    "@jxsuite/collab": "^0.11.10",
-    "@jxsuite/compiler": "^8.6.0",
-    "@jxsuite/create": "^1.8.0",
-    "@jxsuite/erase": "^0.2.0",
-    "@jxsuite/import": "^0.44.1",
-    "@jxsuite/protocol": "^6.3.0",
-    "@jxsuite/runtime": "^6.3.0",
-    "@jxsuite/schema": "^5.6.0",
-    "@jxsuite/site": "^2.6.0",
-    "@jxsuite/starters": "^3.5.0",
+    "@jxsuite/ai": "^0.43.5",
+    "@jxsuite/catalog": "^0.1.13",
+    "@jxsuite/collab": "^0.12.0",
+    "@jxsuite/compiler": "^8.7.0",
+    "@jxsuite/create": "^1.8.1",
+    "@jxsuite/erase": "^0.3.0",
+    "@jxsuite/import": "^0.44.2",
+    "@jxsuite/protocol": "^6.4.0",
+    "@jxsuite/runtime": "^7.0.0",
+    "@jxsuite/schema": "^6.0.0",
+    "@jxsuite/site": "^2.7.0",
+    "@jxsuite/starters": "^3.6.0",
     "@npmcli/arborist": "^10.0.4",
     "chokidar": "^6.0.0",
     "kysely": "^0.29.8",
@@ -76,9 +77,9 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@jxsuite/auth": "^0.8.8",
-    "@jxsuite/connector": "^0.8.8",
-    "@jxsuite/parser": "^4.3.4",
+    "@jxsuite/auth": "^0.8.9",
+    "@jxsuite/connector": "^0.8.9",
+    "@jxsuite/parser": "^5.0.0",
     "@jxsuite/test-support": "^0.0.0",
     "@types/npm-package-arg": "^6.1.4",
     "@types/npmcli__arborist": "^6.3.3",

package/src/code-api.ts

@@ -1,8 +1,8 @@
 /**
  * Code-api.js — OXC-powered code services for the studio function editor
  *
- * Endpoints under /__studio/code/* that format (oxfmt) and lint (oxlint CLI) a function body. A
- * body may be TypeScript (`spec.md` §23.1), so both read it as `.ts`.
+ * Endpoints under /__studio/code/* that format (oxfmt, through `code-format.ts`) and lint (oxlint
+ * CLI) a function body. A body may be TypeScript (`spec.md` §23.1), so both read it as `.ts`.
  */
 
 import { tmpdir } from "node:os";
@@ -11,7 +11,7 @@ import type { JsonValue } from "@jxsuite/schema/types";
 import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
 import { unlink } from "node:fs/promises";
-import { format } from "oxfmt";
+import { formatBody } from "./code-format.ts";
 import { problem } from "./problem.ts";
 
 /** A label's source span; oxlint's other span members pass through to the client unchanged. */
@@ -67,6 +67,10 @@ export function resolveOxlintBin(startDir: string = import.meta.dir): string | n
 // ─── Wrapper utilities ───────────────────────────────────────────────────────
 
 /**
+ * A body inside a function with its parameters, so the linter knows each name it is called with.
+ * The function is not `async`, as the one a document's body becomes is not, so a body that awaits
+ * is told so here and not first when it runs.
+ *
  * @param {string} body
  * @param {string[]} [args]
  */
@@ -75,22 +79,6 @@ function wrapBody(body: string, args: string[] = ["state", "event"]) {
   return `function __jx_fn__(${params}) {\n${body}\n}`;
 }
 
-/** @param {string} formatted */
-function unwrapFormatted(formatted: string) {
-  const lines = formatted.split("\n");
-  // Remove first line (function header) and last non-empty line (closing brace)
-  let end = lines.length - 1;
-  while (end > 0 && lines[end]!.trim() === "") {
-    end -= 1;
-  }
-  if (lines[end]!.trim() === "}") {
-    end -= 1;
-  }
-  const bodyLines = lines.slice(1, end + 1);
-  // Dedent by one tab (oxfmt uses the project's indentStyle)
-  return bodyLines.map((l) => (l.startsWith("\t") ? l.slice(1) : l)).join("\n");
-}
-
 /**
  * @param {OxcDiagnostic[]} diagnostics
  * @param {number} headerLen
@@ -137,17 +125,16 @@ export async function handleCodeApi(req: Request, url: URL) {
   // ── Format ─────────────────────────────────────────────────────────────────
 
   if (action === "format") {
-    const { code, args } = body;
+    const { code } = body;
     if (!code?.trim()) {
       return Response.json({ code: "", errors: [] });
     }
 
     try {
-      const wrapped = wrapBody(code, args);
-      const result = await format("fn.ts", wrapped, { useTabs: true });
+      const result = await formatBody(code);
       return Response.json({
-        code: unwrapFormatted(result.code),
-        errors: result.errors,
+        code: result.code,
+        errors: result.errors.map((message) => ({ message })),
       });
     } catch (error) {
       return Response.json({

package/src/code-format.ts

@@ -0,0 +1,134 @@
+/**
+ * How the code a document holds is formatted: a function body (`spec.md` §23.1) and a document's
+ * script (§23.2), by `oxfmt`, as TypeScript, at its defaults. Studio's code editor and `jx format`
+ * both ask here, so a body one of them has formatted is one the other leaves alone.
+ *
+ * A body is the statements of a function and no file of its own, so it is formatted inside one and
+ * taken back out. Taking it out is unindenting it, and a line the formatter did not write must not
+ * be unindented: the lines of a template literal are the string's own text. So a body is formatted
+ * at two depths, and a line is the formatter's where the deeper reading moved it.
+ *
+ * @docs framework/build/cli
+ * @docs studio/logic/code
+ */
+import { format } from "oxfmt";
+
+/** One formatting of one piece of code. */
+export interface FormattedCode {
+  /** The code formatted, or as it was given where it could not be. */
+  code: string;
+  /** Why it could not be, which is nothing where it could. */
+  errors: string[];
+}
+
+/** The columns a line of code may take, counted from where the code starts and not the file. */
+const COLUMNS = 100;
+
+/** What one level of nesting adds to a line. */
+const INDENT = "  ";
+
+/**
+ * What a body is wrapped in, so it may `return`. `async`, as a class method that awaits is: whether
+ * a body may await is its checker's to say, and a formatter that refused would leave it
+ * unformatted.
+ */
+const OPEN = "async function __jx_fn__() {\n";
+
+/** What the formatter says is wrong with a file. */
+type FormatError = Awaited<ReturnType<typeof format>>["errors"][number];
+
+/** What is wrong, and the line of the code it is on where the formatter gives it a place. */
+function told(error: FormatError, text: string, placing: Placing): string {
+  const at = error.labels[0]?.start;
+  if (at === undefined) {
+    return error.message;
+  }
+  // The place is counted in bytes of UTF-8, and a line break is one of those in any text.
+  const line = Buffer.from(text).subarray(0, at).toString().split("\n").length - placing.above;
+  // Code that stops short is found wrong where the file goes on, which is its own last line.
+  return `${error.message} (line ${Math.min(line, placing.lines)})`;
+}
+
+/** Where code is in the file it is formatted as. */
+interface Placing {
+  /** The lines of the file above the code, which a line number in the code does not count. */
+  above: number;
+  /** The lines the code has. */
+  lines: number;
+  /** The columns the file's nesting takes, which every line is allowed over {@link COLUMNS}. */
+  room: number;
+}
+
+/** Format a `.ts` file's text. */
+async function formatted(name: string, text: string, placing: Placing): Promise<FormattedCode> {
+  const { code, errors } = await format(name, text, {
+    printWidth: COLUMNS + placing.room,
+    tabWidth: INDENT.length,
+    useTabs: false,
+  });
+  return { code, errors: errors.map((error) => told(error, text, placing)) };
+}
+
+/**
+ * A body inside its function, with `blocks` blocks around it. Each level is given back the columns
+ * it takes, so a line breaks where it would at no depth at all.
+ */
+async function nested(body: string, blocks: number): Promise<FormattedCode> {
+  const text = `${OPEN}${"{\n".repeat(blocks)}${body}\n${"}\n".repeat(blocks)}}\n`;
+  const above = 1 + blocks;
+  const placing = { above, lines: body.split("\n").length, room: INDENT.length * above };
+  const { code, errors } = await formatted("body.ts", text, placing);
+  const lines = code.split("\n");
+  // The function's line and each block's come off the front, and their braces and the last newline
+  // Off the end.
+  return { code: lines.slice(above, -(above + 1)).join("\n"), errors };
+}
+
+/** One line of a body with its nesting taken off, or null where the two readings disagree. */
+function unindented(line: string, deeper: string | undefined): string | null {
+  if (deeper === line) {
+    // Not moved by a level of nesting, so not the formatter's to indent: a template literal's text.
+    return line;
+  }
+  return deeper === `${INDENT}${line}` && line.startsWith(INDENT)
+    ? line.slice(INDENT.length)
+    : null;
+}
+
+/**
+ * Format a function body.
+ *
+ * @param body The body as written.
+ * @returns The body formatted. As written, with why, where it does not parse, and as written with
+ *   nothing to say where its lines cannot be told from a string's.
+ */
+export async function formatBody(body: string): Promise<FormattedCode> {
+  if (body.trim() === "") {
+    return { code: "", errors: [] };
+  }
+  const [shallow, deep] = await Promise.all([nested(body, 0), nested(body, 1)]);
+  if (shallow.errors.length > 0) {
+    return { code: body, errors: shallow.errors };
+  }
+  const deeper = deep.code.split("\n");
+  const lines = shallow.code.split("\n").map((line, at) => unindented(line, deeper[at]));
+  const kept = lines.flatMap((line) => (line === null ? [] : [line]));
+  const agreed = kept.length === lines.length && deeper.length === lines.length;
+  return { code: agreed ? kept.join("\n") : body, errors: [] };
+}
+
+/**
+ * Format a document's script, which is a module.
+ *
+ * @param script The module as written.
+ * @returns The module formatted, without the newline a file ends with, which a string has no use
+ *   for. As written, with why, where it does not parse.
+ */
+export async function formatScript(script: string): Promise<FormattedCode> {
+  if (script.trim() === "") {
+    return { code: "", errors: [] };
+  }
+  const placing = { above: 0, lines: script.trimEnd().split("\n").length, room: 0 };
+  const { code, errors } = await formatted("script.ts", script, placing);
+  return errors.length > 0 ? { code: script, errors } : { code: code.replace(/\n$/u, ""), errors };
+}

package/src/dev.ts

@@ -15,11 +15,14 @@
 import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, normalize, resolve, sep } from "node:path";
+import { isScriptSpecifier } from "@jxsuite/schema/document-scripts";
 import { errorMessage } from "@jxsuite/schema/parse";
 import type { JsonObject } from "@jxsuite/schema/types";
 import { projectDevEnv } from "./dev-vars.ts";
 import { problem } from "./problem.ts";
-import { callServerExport } from "./resolve.ts";
+import { callServerExport, importServerScript } from "./resolve.ts";
+import type { ModuleNamespace } from "./resolve.ts";
+import { serverScriptAddress } from "./server-script.ts";
 import { createDevServer } from "./server.ts";
 import { injectSSE } from "./watch.ts";
 import { hasProjectFile } from "@jxsuite/schema/project-file/node";
@@ -100,7 +103,10 @@ export function createDistMiddleware(
 /** One server entry the last build collected: the export, and where the site worker imports it from. */
 export interface ServerEntry {
   exportName: string;
-  /** A `./` path from the project root, or a bare specifier, exactly as the worker bundle reads it. */
+  /**
+   * A `./` path from the project root, a document's server script by its qualified specifier, or a
+   * bare specifier, exactly as the worker bundle reads it.
+   */
   src: string;
 }
 
@@ -132,7 +138,8 @@ async function readArguments(req: Request): Promise<JsonObject> {
  * `process.env` under the project's `.dev.vars`), so it reads the same secrets in development.
  *
  * Each module is resolved as the worker bundle resolves it, from the project root: a `./` path
- * against the root, any other specifier through the project's own `package.json`. It applies no
+ * against the root, a document's own server script (`jx-script:pages/x.json#server`, spec.md §23.2)
+ * from that document, any other specifier through the project's own `package.json`. It applies no
  * containment check, because the module path comes from the build and never from the request;
  * containment stays in the `/__jx_server__` proxy, where the request names the module.
  *
@@ -156,18 +163,29 @@ export function createServerFunctionMiddleware(
       return problem("notFound", `The last build collected no server function "${name}"`);
     }
 
-    let modulePath: string;
-    try {
-      modulePath =
-        entry.src.startsWith("./") || entry.src.startsWith("../")
-          ? resolve(root, entry.src)
-          : requireFromProject.resolve(entry.src);
-    } catch (error) {
-      return Response.json({ error: errorMessage(error), ok: false }, { status: 500 });
+    let module: string | (() => Promise<ModuleNamespace>);
+    if (isScriptSpecifier(entry.src)) {
+      // A document's own server script (spec.md §23.2), which the build named by its project path.
+      const address = serverScriptAddress(entry.src);
+      if (address.kind !== "path") {
+        const error = `"${entry.src}" names no server script of a document in this project`;
+        return Response.json({ error, ok: false }, { status: 500 });
+      }
+      const documentPath = resolve(root, address.path);
+      module = () => importServerScript(documentPath, root);
+    } else {
+      try {
+        module =
+          entry.src.startsWith("./") || entry.src.startsWith("../")
+            ? resolve(root, entry.src)
+            : requireFromProject.resolve(entry.src);
+      } catch (error) {
+        return Response.json({ error: errorMessage(error), ok: false }, { status: 500 });
+      }
     }
 
     const args = await readArguments(req);
-    const result = await callServerExport(modulePath, entry.exportName, args, projectDevEnv(root));
+    const result = await callServerExport(module, entry.exportName, args, projectDevEnv(root));
     if (result.ok) {
       return Response.json(result.value ?? null);
     }

package/src/format.ts

@@ -0,0 +1,271 @@
+/**
+ * `jx format`: format the code a `.jxn` file holds, and the file around it (compiler.md §2.3).
+ *
+ * The code is what `oxfmt` cannot reach, because it is a string in a file `oxfmt` does not read:
+ * every `Function` entry's body and both of a document's scripts. The file around it is the
+ * writer's to lay out. A file with no comment is written whole, in the one form the writer has. A
+ * file with a comment is merged the way a save from Studio is (spec.md §22.4), so that only what
+ * the formatter changed is rewritten and no comment is lost.
+ *
+ * This runs under Bun for the same reason `jx convert` does, so `@jxsuite/compiler`'s CLI resolves
+ * it from the project and spawns it.
+ *
+ * @docs framework/build/cli
+ * @docs framework/concepts/jxn-files
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { isFunctionEntry, isJsonObject, isString } from "@jxsuite/schema/guards";
+import {
+  classifyJxn,
+  countJxnComments,
+  isJxnPath,
+  parseJxn,
+  parseProject,
+  serializeJxn,
+  serializeProject,
+} from "@jxsuite/schema/jxn";
+import { errorMessage } from "@jxsuite/schema/parse";
+import type { JsonObject, JsonValue, JxDocument, ProjectConfig } from "@jxsuite/schema/types";
+import { formatBody, formatScript } from "./code-format.ts";
+import type { FormattedCode } from "./code-format.ts";
+
+/** Code in a file that could not be formatted. */
+export interface FormatProblem {
+  /** Why not, as the formatter says it. */
+  message: string;
+  /** The JSON Pointer of the string that holds the code. */
+  pointer: string;
+}
+
+/** One `.jxn` file's text, formatted. */
+export interface FormattedJxn {
+  /** The code left as written, each with why. */
+  problems: FormatProblem[];
+  text: string;
+}
+
+/** What formats one piece of code. */
+type CodeFormatter = (code: string) => Promise<FormattedCode>;
+
+/** The folders under a named one that hold nothing an author wrote. */
+const SKIPPED = new Set(["dist", "node_modules"]);
+
+/** A JSON Pointer one step down. */
+function pointerInto(pointer: string, key: string | number): string {
+  return `${pointer}/${String(key).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+}
+
+/**
+ * What formats the string a member holds, or null where it is not code: a `Function` entry's body,
+ * wherever the entry sits, and each side of the document's `$script`. Any other `body` may be data
+ * (a `Request`'s payload), and a template is left to its author.
+ */
+function formatterOf(owner: JsonObject, pointer: string, key: string): CodeFormatter | null {
+  if (key === "body") {
+    return isFunctionEntry(owner) ? formatBody : null;
+  }
+  return pointer === "/$script" && (key === "client" || key === "server") ? formatScript : null;
+}
+
+/** Copy a tree, formatting the code in it. */
+async function walk(
+  value: JsonValue,
+  pointer: string,
+  problems: FormatProblem[],
+): Promise<JsonValue> {
+  if (Array.isArray(value)) {
+    const items: JsonValue[] = [];
+    for (const [index, item] of value.entries()) {
+      items.push(await walk(item, pointerInto(pointer, index), problems));
+    }
+    return items;
+  }
+  if (!isJsonObject(value)) {
+    return value;
+  }
+  const entries: [string, JsonValue][] = [];
+  for (const [key, child] of Object.entries(value)) {
+    const at = pointerInto(pointer, key);
+    const formatter = formatterOf(value, pointer, key);
+    // Nothing but white space is no code, and is left as the nothing its author wrote.
+    if (formatter === null || !isString(child) || child.trim() === "") {
+      entries.push([key, await walk(child, at, problems)]);
+    } else {
+      const { code, errors } = await formatter(child);
+      problems.push(...errors.map((message) => ({ message, pointer: at })));
+      entries.push([key, code]);
+    }
+  }
+  // Built from entries: assigning `__proto__` would set the copy's prototype.
+  return Object.fromEntries(entries);
+}
+
+/**
+ * Format one `.jxn` file's text: a document or a project file.
+ *
+ * @param text The file.
+ * @returns The file formatted, and the code in it that was left as written.
+ * @throws {JxnError} When the file cannot be read, or holds what Jx Notation cannot spell.
+ */
+export async function formatJxn(text: string): Promise<FormattedJxn> {
+  const problems: FormatProblem[] = [];
+  const isProject = classifyJxn(text) === "project";
+  const read: unknown = isProject ? parseProject(text) : parseJxn(text);
+  const formatted = await walk(isJsonObject(read) ? read : {}, "", problems);
+  // Merged into the file it replaces only where there is a comment to lose (spec.md §22.4).
+  const previous = countJxnComments(text) > 0 ? text : undefined;
+  /* SAFETY: `walk` copies what was read member for member, and puts a string where a string was, so
+     the copy is whatever the file it came from was. */
+  const written = isProject
+    ? serializeProject(formatted as ProjectConfig, previous)
+    : serializeJxn(formatted as JxDocument, previous);
+  return { problems, text: written };
+}
+
+/** Every `.jxn` file a path names: itself, or what is under it. */
+function expand(path: string): string[] {
+  // A path that is not there comes through as itself, so the report can say so.
+  if (!existsSync(path) || !statSync(path).isDirectory()) {
+    return [path];
+  }
+  return readdirSync(path, { withFileTypes: true }).flatMap((entry) => {
+    const child = join(path, entry.name);
+    if (entry.isDirectory()) {
+      return entry.name.startsWith(".") || SKIPPED.has(entry.name) ? [] : expand(child);
+    }
+    return isJxnPath(entry.name) ? [child] : [];
+  });
+}
+
+/** What happened to one file. */
+export interface FormatRow {
+  /** Its text is not what formatting it gives. */
+  changed: boolean;
+  /** Its path from the root. */
+  path: string;
+  /** What is wrong with it, each as the line the report prints after the path. */
+  problems: string[];
+}
+
+/** Format one file where it is, or say what formatting it would do. */
+async function formatFile(root: string, path: string, check: boolean): Promise<FormatRow> {
+  const row: FormatRow = {
+    changed: false,
+    path: relative(root, path).replaceAll("\\", "/"),
+    problems: [],
+  };
+  if (!existsSync(path)) {
+    row.problems.push(": there is no such file");
+    return row;
+  }
+  if (!isJxnPath(path)) {
+    row.problems.push(": only a .jxn file holds code this can reach");
+    return row;
+  }
+  try {
+    const text = await readFile(path, "utf8");
+    const formatted = await formatJxn(text);
+    row.problems = formatted.problems.map((problem) => `#${problem.pointer}: ${problem.message}`);
+    row.changed = formatted.text !== text;
+    if (row.changed && !check) {
+      await writeFile(path, formatted.text);
+    }
+  } catch (error) {
+    row.problems.push(`: ${errorMessage(error)}`);
+  }
+  return row;
+}
+
+/**
+ * Format the `.jxn` files under some paths.
+ *
+ * @param root What the paths are relative to.
+ * @param paths Files and directories.
+ * @param check Say what would change, and write nothing.
+ */
+export async function formatFiles(
+  root: string,
+  paths: readonly string[],
+  check: boolean,
+): Promise<FormatRow[]> {
+  const files = new Set(paths.flatMap((item) => expand(resolve(root, item))));
+  const rows: FormatRow[] = [];
+  for (const path of [...files].toSorted()) {
+    rows.push(await formatFile(root, path, check));
+  }
+  return rows;
+}
+
+/** What `jx format` was given. */
+export interface FormatArgs {
+  check: boolean;
+  paths: string[];
+  root: string;
+}
+
+/**
+ * Read `jx format`'s arguments.
+ *
+ * @param argv The arguments after the command.
+ * @returns What was asked, or null when it names an option there is not.
+ */
+export function parseFormatArgs(argv: readonly string[]): FormatArgs | null {
+  const paths: string[] = [];
+  let root = process.cwd();
+  let check = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    if (arg === "--root") {
+      index += 1;
+      root = resolve(argv[index] ?? root);
+    } else if (arg === "--check") {
+      check = true;
+    } else if (arg.startsWith("-")) {
+      return null;
+    } else {
+      paths.push(arg);
+    }
+  }
+  // With no path named, the project is what is formatted.
+  return { check, paths: paths.length > 0 ? paths : ["."], root };
+}
+
+/**
+ * Run `jx format`.
+ *
+ * @param argv The arguments after the command.
+ * @param print Where the report goes.
+ * @returns The exit code: 1 when a file or code in one could not be formatted, or when `--check`
+ *   found a file that formatting would change.
+ */
+export async function runFormat(
+  argv: readonly string[],
+  print: (line: string) => void = console.log,
+): Promise<number> {
+  const args = parseFormatArgs(argv);
+  if (!args) {
+    print("Usage: jx format [paths…] [--check]");
+    return 2;
+  }
+  const rows = await formatFiles(args.root, args.paths, args.check);
+  for (const row of rows) {
+    for (const problem of row.problems) {
+      print(`${row.path}${problem}`);
+    }
+    if (row.changed) {
+      print(`${row.path} ${args.check ? "would be formatted" : "formatted"}`);
+    }
+  }
+  const changed = rows.filter((row) => row.changed).length;
+  print(
+    `${changed} file(s) ${args.check ? "would be formatted" : "formatted"}, ${rows.length - changed} left as written`,
+  );
+  const failed = rows.some((row) => row.problems.length > 0) || (args.check && changed > 0);
+  return failed ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exitCode = await runFormat(process.argv.slice(2));
+}