@jxsuite/compiler 8.4.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -52,10 +52,11 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/create": "^1.6.0",
-    "@jxsuite/runtime": "^6.2.1",
-    "@jxsuite/schema": "^5.4.0",
-    "@jxsuite/site": "^2.5.0",
+    "@jxsuite/create": "^1.7.0",
+    "@jxsuite/erase": "^0.1.0",
+    "@jxsuite/runtime": "^6.2.2",
+    "@jxsuite/schema": "^5.5.0",
+    "@jxsuite/site": "^2.5.1",
     "@vue/reactivity": "3.5.44",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
@@ -63,8 +64,8 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/connector": "^0.8.6",
-    "@jxsuite/parser": "^4.3.2",
+    "@jxsuite/connector": "^0.8.7",
+    "@jxsuite/parser": "^4.3.3",
     "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4"
   }

package/src/compiler.ts

@@ -13,6 +13,7 @@
  * @version 3.0.0
  */
 
+import { erasedDocument } from "./erased.ts";
 import { readFileSync } from "node:fs";
 import {
   DEFAULT_LIT_HTML_SRC,
@@ -109,6 +110,8 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   } else {
     raw = sourcePath;
   }
+  // Function bodies as JavaScript before anything analyses them (spec.md §23.1).
+  raw = erasedDocument(raw, isString(sourcePath) ? sourcePath : "the document");
 
   // Route 0: .class.json schema-defined class → JS class module
   if (isClassDef(raw)) {

package/src/erased.ts

@@ -0,0 +1,60 @@
+/**
+ * Documents as the compiler reads them: with the TypeScript in their function bodies erased, once,
+ * as each is read (`spec.md` §23.1, `compiler.md` §2.3). Everything after this, the analysis that
+ * classifies a body and every emitter, sees JavaScript, so none of it changes.
+ *
+ * A body that was already JavaScript and reads differently as TypeScript (`a < b > (c)`) is said
+ * once per place, on stderr, and the build goes on with the TypeScript reading.
+ *
+ * @docs framework/concepts/functions
+ */
+import { eraseClass, eraseDocument } from "@jxsuite/erase";
+import type { EraseWarning } from "@jxsuite/erase";
+import type { JsonValue, JxClassDef, JxDocument } from "@jxsuite/schema/types";
+
+/** Every warning already printed, so a document read twice says each thing once. */
+const said = new Set<string>();
+
+/** Print what erasing found that did not stop it. */
+function report(warnings: readonly EraseWarning[]): void {
+  for (const { path, pointer, problem } of warnings) {
+    const line = `${path}${pointer} (line ${problem.line}, column ${problem.column}): ${problem.message}`;
+    if (!said.has(line)) {
+      said.add(line);
+      console.warn(`Warning: ${line}`);
+    }
+  }
+}
+
+/**
+ * A document with its function bodies as JavaScript.
+ *
+ * @param document The document as read.
+ * @param path Where it was read from, which names it in a message.
+ * @throws {import("@jxsuite/erase").EraseError} When a body uses TypeScript that cannot be erased.
+ */
+export function erasedDocument<T extends JsonValue | JxDocument | JxClassDef>(
+  document: T,
+  path: string,
+): T {
+  const warnings: EraseWarning[] = [];
+  const erased = eraseDocument(document, path, warnings);
+  report(warnings);
+  return erased;
+}
+
+/**
+ * A class definition with its members' bodies as JavaScript.
+ *
+ * @param definition The class definition as read.
+ * @param path Where it was read from.
+ */
+export function erasedClass<T extends JsonValue | JxDocument | JxClassDef>(
+  definition: T,
+  path: string,
+): T {
+  const warnings: EraseWarning[] = [];
+  const erased = eraseClass(definition, path, warnings);
+  report(warnings);
+  return erased;
+}

package/src/shared.ts

@@ -49,6 +49,7 @@ import {
   isTemplateString,
   paramNames,
   tagNameCandidates,
+  maskCode,
 } from "@jxsuite/schema/guards";
 import type { TagNameSlot } from "@jxsuite/schema/guards";
 import { resolveShadowMode, styleScopePrefix } from "./shadow.ts";
@@ -604,6 +605,62 @@ const STATE_ASSIGNMENT_RE =
 const STATE_MUTATING_METHOD_RE =
   /\bstate\.([A-Za-z_$][\w$]*)\s*\.\s*(?:push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin)\s*\(/g;
 
+/** A character that continues an identifier, or a `.` that makes `state` someone's member. */
+const JOINS_STATE = /[\w$.]/u;
+
+/** A character that continues an identifier. */
+const CONTINUES_NAME = /[\w$]/u;
+
+/** Whether `state` at `at` in `read` is the one to move: standalone, and a member read unless bare. */
+function movesState(read: string, at: number, bare: boolean): boolean {
+  if (at > 0 && JOINS_STATE.test(read.charAt(at - 1))) {
+    return false;
+  }
+  let next = at + "state".length;
+  if (bare) {
+    return !CONTINUES_NAME.test(read.charAt(next));
+  }
+  while (/\s/u.test(read.charAt(next))) {
+    next += 1;
+  }
+  return read.charAt(next) === ".";
+}
+
+/**
+ * Rewrite `state` in emitted code to what holds it there (`this.state`, `s`): the one way every
+ * target does it (`spec.md` §23.1). Only a standalone `state` moves, so `prevstate.n` stays itself,
+ * and in a body only code moves, so a string or a comment that mentions `state.` is left as
+ * written.
+ *
+ * @param text The body, or an expression.
+ * @param to What `state` becomes.
+ * @param options `bare` moves `state` alone too, not only `state.member`; `code: false` reads text
+ *   that is not a body (an attribute's template), where nothing is a string or a comment.
+ */
+export function rewriteState(
+  text: string,
+  to: string,
+  options: { bare?: boolean; code?: boolean } = {},
+): string {
+  // Most text never names `state`, and every emitter calls this on every body and template.
+  if (!text.includes("state")) {
+    return text;
+  }
+  const bare = options.bare === true;
+  const read = options.code === false ? text : maskCode(text);
+  /* A scan rather than a lookbehind pattern: every emitter runs this on every body and template,
+     and JavaScriptCore runs `(?<!…)` on its slow path, which a compile benchmark measured. */
+  let out = "";
+  let last = 0;
+  for (let at = read.indexOf("state"); at !== -1; at = read.indexOf("state", at + 1)) {
+    if (movesState(read, at, bare)) {
+      out += text.slice(last, at) + to;
+      last = at + "state".length;
+    }
+  }
+  return out + text.slice(last);
+}
+
 /**
  * Collect every state key a handler writes to, across all the forms a body can take: a string body,
  * a structured body (spec §20), and an `$expression` node with a mutating operator.
@@ -618,11 +675,16 @@ const STATE_MUTATING_METHOD_RE =
  */
 function collectAssignedStateKeys(node: JxDocumentValue | undefined, into: Set<string>) {
   if (isString(node)) {
-    for (const m of node.matchAll(STATE_ASSIGNMENT_RE)) {
+    if (!node.includes("state.")) {
+      return;
+    }
+    // Code only: an assignment a comment or a string mentions writes nothing (spec.md §23.1).
+    const code = maskCode(node);
+    for (const m of code.matchAll(STATE_ASSIGNMENT_RE)) {
       // SAFETY: the pattern's one capture group is outside any optional part, so a match has it.
       into.add(m[1] as string);
     }
-    for (const m of node.matchAll(STATE_MUTATING_METHOD_RE)) {
+    for (const m of code.matchAll(STATE_MUTATING_METHOD_RE)) {
       // SAFETY: the pattern's one capture group is outside any optional part, so a match has it.
       into.add(m[1] as string);
     }

package/src/site/layout-resolver.ts

@@ -8,6 +8,7 @@
  * and saying which file was wrong when it is.
  */
 
+import { erasedDocument } from "../erased.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { parseNativeDocument } from "@jxsuite/schema/jxn";
 import { errorMessage } from "@jxsuite/schema/parse";
@@ -27,7 +28,10 @@ export function nodeLayoutLoader(projectRoot: string): (layoutRef: string) => Jx
       throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
     }
     try {
-      return parseNativeDocument(readFileSync(layoutPath, "utf8"), layoutPath);
+      return erasedDocument(
+        parseNativeDocument(readFileSync(layoutPath, "utf8"), layoutPath),
+        layoutPath,
+      );
     } catch (error) {
       throw new Error(`Invalid layout at ${layoutPath}: ${errorMessage(error)}`, {
         cause: error,

package/src/site/pages-discovery.ts

@@ -16,6 +16,7 @@
  * genuinely needs a filesystem: the walk, the `$layout` peek, and `$paths` expansion.
  */
 
+import { erasedDocument } from "../erased.ts";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { isNativeDocumentPath, parseNativeDocument } from "@jxsuite/schema/jxn";
@@ -82,7 +83,7 @@ export async function readPageDocument(
 ): Promise<JxDocument> {
   const source = readFileSync(filePath, "utf8");
   if (isNativeDocumentPath(filePath)) {
-    return parseNativeDocument(source, filePath);
+    return erasedDocument(parseNativeDocument(source, filePath), filePath);
   }
   const ext = extname(filePath).toLowerCase();
   const entry = registry?.byExtension(ext, "parse");
@@ -93,7 +94,8 @@ export async function readPageDocument(
         `e.g. "@jxsuite/parser".`,
     );
   }
-  return await entry.parseDocument(source);
+  // A format's page holds function bodies too (spec.md §23.1).
+  return erasedDocument(await entry.parseDocument(source), filePath);
 }
 
 /**

package/src/site/validate-command.ts

@@ -20,6 +20,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 { eraseDocument } from "@jxsuite/erase";
+import type { EraseWarning } from "@jxsuite/erase";
 import { createRequire } from "node:module";
 import { join, relative, resolve } from "node:path";
 import { generateClassSchema } from "@jxsuite/schema";
@@ -65,8 +67,11 @@ export interface ProjectTreeLintFinding {
   file: string;
   /** The node's path inside the document. */
   path: (string | number)[];
-  /** Which lint: `popover`, `dialog`, `accessibility`, or `notation` for a `.jxn` file's text. */
-  source: "popover" | "dialog" | "accessibility" | "notation";
+  /**
+   * Which lint: `popover`, `dialog`, `accessibility`, `notation` for a `.jxn` file's text, or
+   * `function-body` for a body whose meaning reading it as TypeScript changes (`spec.md` §23.1).
+   */
+  source: "popover" | "dialog" | "accessibility" | "notation" | "function-body";
   rule: string;
   message: string;
   detail: string;
@@ -221,6 +226,12 @@ export async function validateProjectTree(
         continue;
       }
       const doc = read.document;
+      const bodies = checkBodies(doc, relative(root, file));
+      lint.push(...bodies.warnings);
+      if (bodies.failure !== null) {
+        issues.push(bodies.failure);
+        continue;
+      }
       if (validateDoc(doc)) {
         /*
          * Only a well-formed document is judged; a schema error is the report for the rest.
@@ -241,7 +252,11 @@ export async function validateProjectTree(
   for (const file of walkClassFiles(root)) {
     checked += 1;
     const doc = readJson(file);
-    if (!validateClass(doc)) {
+    const bodies = checkBodies(doc, relative(root, file));
+    lint.push(...bodies.warnings);
+    if (bodies.failure !== null) {
+      issues.push(bodies.failure);
+    } else if (!validateClass(doc)) {
       issues.push({ errors: validateClass.errors ?? [], file: relative(root, file) });
     }
   }
@@ -315,6 +330,36 @@ function readDocumentFile(file: string, name: string): ReadDocumentFile {
   }
 }
 
+/** What checking a document's function bodies found: an issue that stops it, and warnings. */
+interface BodyCheck {
+  failure: ProjectTreeIssue | null;
+  warnings: ProjectTreeLintFinding[];
+}
+
+/**
+ * Whether every function body in a document is TypeScript that can be erased (`spec.md` §23.1): a
+ * body that cannot is an issue, as it stops `jx build`, and one that reads differently as
+ * TypeScript than as the JavaScript it already was is a warning.
+ */
+function checkBodies(document: JsonValue, name: string): BodyCheck {
+  const found: EraseWarning[] = [];
+  try {
+    eraseDocument(document, name, found);
+  } catch (error) {
+    return { failure: { errors: [{ message: errorMessage(error) }], file: name }, warnings: [] };
+  }
+  const warnings = found.map(({ pointer, problem }): ProjectTreeLintFinding => ({
+    detail: problem.message,
+    file: name,
+    message: `${pointer} (line ${problem.line}, column ${problem.column}): ${problem.message}`,
+    path: pointer.split("/").slice(1),
+    rule: "typescript-reading",
+    severity: "warn",
+    source: "function-body",
+  }));
+  return { failure: null, warnings };
+}
+
 /** A `.jxn` file's document, as the JSON value it is. */
 function readJxnValue(text: string): JsonValue {
   const document = parseJxn(text);

package/src/targets/compile-class.ts

@@ -5,6 +5,7 @@
  * Schema 2020-12 class definition.
  */
 
+import { erasedClass } from "../erased.ts";
 import type {
   JxClassCtorDef,
   JxClassDef,
@@ -20,7 +21,9 @@ import { isString } from "@jxsuite/schema/guards";
  * @param {JxClassDef} classDef - Parsed .class.json content (must have $prototype: "Class")
  * @returns {string} JavaScript module source code
  */
-export function compileClassJson(classDef: JxClassDef) {
+export function compileClassJson(authored: JxClassDef) {
+  // Member bodies as JavaScript before anything splices them (spec.md §23.1).
+  const classDef = erasedClass(authored, authored.title ?? "a class");
   const className = classDef.title;
   if (!className) {
     throw new Error("compileClassJson: missing title (class name)");

package/src/targets/compile-client.ts

@@ -774,7 +774,8 @@ function emitLitMapTemplate(def: JxMutableNode | null | undefined, preformatted
        * has: a repeater handler is emitted inline and needs inline source.
        */
       const body = mapRefsToLit(val.body as string);
-      attrs += ` @${eventName}=\${(e) => { ${body} }}`;
+      // The newline ends a last-line comment before the brace does.
+      attrs += ` @${eventName}=\${(e) => { ${body}\n}}`;
     } else if (isNonNullObject(val) && "$expression" in val) {
       /*
        * SAFETY: an `on*` member carrying `$expression` is a Shape 5 expression entry, whose
@@ -1005,7 +1006,7 @@ function emitClientModule(
       const argNames = def.args ?? ["state"];
       const callArgs = argNames.map((a: string) => (a === "state" ? "state" : "e")).join(", ");
       lines.push(
-        `  ${objectKey(key)}: (e) => { const fn = (${argNames.join(", ")}) => { ${def.body} }; fn(${
+        `  ${objectKey(key)}: (e) => { const fn = (${argNames.join(", ")}) => { ${def.body}\n}; fn(${
           callArgs
         }); },`,
       );

package/src/targets/compile-element.ts

@@ -5,6 +5,7 @@
  * state and lit-html for rendering.
  */
 
+import { erasedDocument } from "../erased.ts";
 import { RESERVED_KEYS, camelToKebab } from "@jxsuite/runtime";
 import {
   ATTR_HELPER,
@@ -26,6 +27,7 @@ import {
   escapeHtml,
   isMutating,
   isSchemaOnly,
+  rewriteState,
   serverCallHelperSource,
   srcExportName,
   srcImportBinding,
@@ -144,8 +146,10 @@ export async function compileElement(
         }
         doc = await entry.parseDocument(readFileSync(filePath, "utf8"));
       }
+      // Function bodies as JavaScript before anything analyses them (spec.md §23.1).
+      doc = erasedDocument(doc, filePath);
     } else {
-      doc = srcPath;
+      doc = erasedDocument(srcPath, srcPath.tagName ?? "a component");
       filePath = null;
       if (doc.tagName && visited.has(doc.tagName)) {
         return;
@@ -665,7 +669,7 @@ export function emitElementModule(
   for (const [key, template] of templateEntries) {
     lines.push(
       "",
-      `    ${refAccessor("this.state", escapeToken(key))} = computed(() => ${templateValueSource(template.replaceAll("state.", "this.state."))});`,
+      `    ${refAccessor("this.state", escapeToken(key))} = computed(() => ${templateValueSource(rewriteState(template, "this.state", { code: false }))});`,
     );
   }
 
@@ -686,7 +690,7 @@ export function emitElementModule(
       );
     } else {
       lines.push(`    ${refAccessor("this.state", escapeToken(key))} = computed(() => {`);
-      const body = (isString(def.body) ? def.body : "").replaceAll("state.", "this.state.");
+      const body = rewriteState(isString(def.body) ? def.body : "", "this.state");
       lines.push(`      ${body}`, "    });");
     }
   }
@@ -839,7 +843,7 @@ export function emitElementModule(
       for (const [cssProp, value] of dynamicStyles) {
         const expr = value.replaceAll(
           /\$\{([^}]+)\}/g,
-          (_: string, e: string) => `\${${e.replaceAll("state.", "this.state.")}}`,
+          (_: string, e: string) => `\${${rewriteState(e, "this.state")}}`,
         );
         lines.push(`      this.style['${cssProp}'] = \`${expr}\`;`);
       }
@@ -1521,7 +1525,7 @@ function mapRefToExpr(ref: string) {
  * @returns {string}
  */
 function toLitExpr(str: string) {
-  return str.replaceAll("state.", "s.");
+  return rewriteState(str, "s", { code: false });
 }
 
 /**
@@ -1576,9 +1580,10 @@ function inlineHandlerBody(def: JxFunctionDef) {
     // Body needs no textual rewriting, and a declared `event` stops silently resolving to the
     // Deprecated `window.event` global (any other declared name threw ReferenceError outright).
     const args = declared.map((name: string) => (name === "state" ? "s" : "e")).join(", ");
-    return `((${declared.join(", ")}) => { ${body} })(${args});`;
+    // The newline ends a last-line comment before the brace does.
+    return `((${declared.join(", ")}) => { ${body}\n})(${args});`;
   }
-  return body.replaceAll(/(?<!this\.)state\./g, "s.").replaceAll(/(?<!this\.)state(?!\.)/g, "s");
+  return `${rewriteState(body, "s", { bare: true })}\n`;
 }
 
 /**