@jxsuite/server 0.28.5 → 0.30.1

package/src/refactor/refs.ts

@@ -0,0 +1,236 @@
+/**
+ * Refs.ts — pure document reference engine for rename-refactoring.
+ *
+ * Two passes, both operating on a parsed (JSON) document tree with no filesystem access: -
+ * `rewriteDocRefs` — recompute every file-path reference across a rename (Pillar B). -
+ * `rewriteTagName` — rename a custom-element tag wherever it is used (Pillar C).
+ *
+ * The walk is structure-aware (it dispatches by JSON key), not a blind string search, and mutates
+ * the passed document in place — callers parse a fresh object per file, so this is safe. Precision
+ * comes from `rewriteRef`'s resolve-and-compare gate in paths.ts: a reference is only rewritten
+ * when it actually resolves to the renamed file.
+ */
+
+import { classifyRef, rewriteRef } from "./paths.ts";
+import type { RemapCtx } from "./paths.ts";
+
+/** A single reference rewrite, for the rename report. */
+export interface RefChange {
+  refType: string;
+  from: string;
+  to: string;
+}
+
+export interface RewriteResult {
+  doc: unknown;
+  changes: RefChange[];
+}
+
+/** Matches `url(...)` targets inside a CSS string value, capturing the optional quote. */
+const URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+/** Recompute a scalar string reference under `key`, recording any change. */
+function rewriteScalar(
+  container: Record<string, unknown>,
+  key: string,
+  refType: string,
+  ctx: RemapCtx,
+  changes: RefChange[],
+  rootRelativeBare: boolean,
+): void {
+  const value = container[key];
+  const cls = classifyRef(value);
+  if (cls.kind !== "path") {
+    return;
+  }
+  const out = rewriteRef(cls, ctx, rootRelativeBare);
+  if (out !== null) {
+    changes.push({ from: value as string, refType, to: out });
+    container[key] = out;
+  }
+}
+
+/** Recompute a string array member (e.g. an `$elements` entry), recording any change. */
+function rewriteIndexed(
+  arr: unknown[],
+  index: number,
+  refType: string,
+  ctx: RemapCtx,
+  changes: RefChange[],
+): void {
+  const value = arr[index];
+  const cls = classifyRef(value);
+  if (cls.kind !== "path") {
+    return;
+  }
+  const out = rewriteRef(cls, ctx, false);
+  if (out !== null) {
+    changes.push({ from: value as string, refType, to: out });
+    arr[index] = out;
+  }
+}
+
+/** Rewrite every `url(...)` target inside a CSS string. */
+function rewriteUrls(value: string, ctx: RemapCtx, changes: RefChange[]): string {
+  return value.replaceAll(URL_RE, (match, quote: string, inner: string) => {
+    const cls = classifyRef(inner.trim());
+    if (cls.kind !== "path") {
+      return match;
+    }
+    const out = rewriteRef(cls, ctx, false);
+    if (out === null) {
+      return match;
+    }
+    changes.push({ from: inner.trim(), refType: "url", to: out });
+    return `url(${quote}${out}${quote})`;
+  });
+}
+
+/** Walk a `style` value tree, rewriting `url(...)` in every string it contains. */
+function walkStyle(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
+  if (Array.isArray(node)) {
+    const arr = node as unknown[];
+    for (let i = 0; i < arr.length; i += 1) {
+      const item = arr[i];
+      if (typeof item === "string") {
+        const out = rewriteUrls(item, ctx, changes);
+        if (out !== item) {
+          arr[i] = out;
+        }
+      } else {
+        walkStyle(item, ctx, changes);
+      }
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    if (typeof value === "string") {
+      const out = rewriteUrls(value, ctx, changes);
+      if (out !== value) {
+        obj[key] = out;
+      }
+    } else {
+      walkStyle(value, ctx, changes);
+    }
+  }
+}
+
+/** Recursive document walk dispatching each reference-bearing key. */
+function walk(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
+  if (Array.isArray(node)) {
+    for (const item of node as unknown[]) {
+      walk(item, ctx, changes);
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    switch (key) {
+      case "$ref": {
+        // File-path $ref only; state-scope refs (#/…, $map/…) are filtered by classifyRef.
+        rewriteScalar(obj, key, "$ref", ctx, changes, false);
+        break;
+      }
+      case "$layout": {
+        rewriteScalar(obj, key, "$layout", ctx, changes, true);
+        break;
+      }
+      case "$src":
+      case "$implementation": {
+        rewriteScalar(obj, key, key, ctx, changes, false);
+        break;
+      }
+      case "src":
+      case "href": {
+        rewriteScalar(obj, key, "attr", ctx, changes, false);
+        break;
+      }
+      case "imports": {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const imp = value as Record<string, unknown>;
+          for (const name of Object.keys(imp)) {
+            rewriteScalar(imp, name, "imports", ctx, changes, false);
+          }
+        }
+        break;
+      }
+      case "$elements": {
+        if (Array.isArray(value)) {
+          const els = value as unknown[];
+          for (let i = 0; i < els.length; i += 1) {
+            if (typeof els[i] === "string") {
+              rewriteIndexed(els, i, "$elements", ctx, changes);
+            } else {
+              walk(els[i], ctx, changes);
+            }
+          }
+        } else {
+          walk(value, ctx, changes);
+        }
+        break;
+      }
+      case "style": {
+        walkStyle(value, ctx, changes);
+        break;
+      }
+      default: {
+        walk(value, ctx, changes);
+      }
+    }
+  }
+}
+
+/** Rewrite every file-path reference in `doc` for a rename described by `ctx`. Mutates `doc`. */
+export function rewriteDocRefs(doc: unknown, ctx: RemapCtx): RewriteResult {
+  const changes: RefChange[] = [];
+  walk(doc, ctx, changes);
+  return { changes, doc };
+}
+
+/** Recursive walk setting `tagName: newTag` wherever it currently equals `oldTag`. */
+function walkTags(node: unknown, oldTag: string, newTag: string, counter: { n: number }): void {
+  if (Array.isArray(node)) {
+    for (const item of node as unknown[]) {
+      walkTags(item, oldTag, newTag, counter);
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (obj.tagName === oldTag) {
+    obj.tagName = newTag;
+    counter.n += 1;
+  }
+  for (const key of Object.keys(obj)) {
+    walkTags(obj[key], oldTag, newTag, counter);
+  }
+}
+
+/**
+ * Rename a custom-element tag throughout `doc` — instance nodes (`<old-tag>`), mapped-list
+ * `map.tagName`, and the component definition file's own root `tagName`. File references (`$ref`,
+ * `$elements`, `cases`) are intentionally left to `rewriteDocRefs`, so the two passes compose.
+ * Mutates `doc`.
+ */
+export function rewriteTagName(
+  doc: unknown,
+  oldTag: string,
+  newTag: string,
+): { doc: unknown; count: number } {
+  const counter = { n: 0 };
+  if (oldTag !== newTag) {
+    walkTags(doc, oldTag, newTag, counter);
+  }
+  return { count: counter.n, doc };
+}

package/src/refactor/watcher.ts

@@ -0,0 +1,70 @@
+/**
+ * Watcher.ts — a small chokidar wrapper that emits coalesced, batched FS-event payloads to a sink.
+ *
+ * Used by the desktop project session (which has no SSE stream) to push filesystem changes to its
+ * webview over RPC. The dev server keeps its own watcher in watch.ts (intertwined with
+ * build/reload); both share the pure `toFsEvent`/`coalesceFsEvents` helpers.
+ */
+
+import { watch as chokidarWatch } from "chokidar";
+import { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
+import type { FsEventPayload } from "./fs-events.ts";
+
+const IGNORE_SEGMENTS = ["node_modules", ".git", "dist", ".jx", ".direnv", ".devenv"];
+
+function isIgnored(path: string): boolean {
+  const f = path.replaceAll("\\", "/");
+  return IGNORE_SEGMENTS.some((s) => f.includes(`/${s}/`) || f.endsWith(`/${s}`));
+}
+
+export interface FsWatcherHandle {
+  close: () => Promise<void>;
+}
+
+/**
+ * Watch `root`, coalescing rapid changes and delivering batches to `sink`. Returns a handle whose
+ * `close()` stops the watcher and clears any pending batch.
+ */
+export function createFsWatcher(
+  root: string,
+  sink: (events: FsEventPayload[]) => void,
+  opts: { debounce?: number } = {},
+): FsWatcherHandle {
+  const debounceMs = opts.debounce ?? 40;
+  let buffer: FsEventPayload[] = [];
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const watcher = chokidarWatch(root, {
+    ignoreInitial: true,
+    ignorePermissionErrors: true,
+    ignored: (path) => isIgnored(path),
+  });
+
+  watcher.on("all", (eventType, changedPath) => {
+    const event = toFsEvent(eventType, root, changedPath);
+    if (!event) {
+      return;
+    }
+    buffer = coalesceFsEvents(buffer, event);
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      if (buffer.length > 0) {
+        sink(buffer);
+        buffer = [];
+      }
+    }, debounceMs);
+  });
+
+  return {
+    close: async () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      buffer = [];
+      await watcher.close();
+    },
+  };
+}

package/src/resolve.ts

@@ -6,7 +6,34 @@ import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { loadContentTypes } from "@jxsuite/compiler/content-loader";
 import type { DynamicClass } from "@jxsuite/runtime/types";
-import type { JxClassDef } from "@jxsuite/schema/types";
+import type { JxClassDef, ProjectConfig } from "@jxsuite/schema/types";
+
+interface ModuleNamespace {
+  default?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface ClassInstance {
+  resolve?: () => unknown;
+  value?: unknown;
+  [key: string]: unknown;
+}
+
+interface ResolveBody {
+  $src?: string;
+  $prototype?: string;
+  $export?: string;
+  $base?: string;
+  [key: string]: unknown;
+}
+
+interface ServerFunctionBody {
+  $src?: string;
+  $export?: string;
+  $base?: string;
+  arguments?: Record<string, unknown>;
+  [key: string]: unknown;
+}
 
 /**
  * Lazy-load project context (project.json + content types) for class instantiation.
@@ -24,7 +51,7 @@ async function loadProjectContext(projectRoot: string) {
     return null;
   }
   try {
-    const config = JSON.parse(readFileSync(projectJsonPath, "utf8"));
+    const config = JSON.parse(readFileSync(projectJsonPath, "utf8")) as ProjectConfig;
     const contentTypes = config.contentTypes
       ? await loadContentTypes(projectRoot, config)
       : new Map();
@@ -46,9 +73,9 @@ export async function handleResolve(
   root: string,
   activeProjectRoot: string | null = null,
 ) {
-  let body;
+  let body: ResolveBody;
   try {
-    body = await req.json();
+    body = (await req.json()) as ResolveBody;
   } catch {
     return new Response("Invalid JSON body", { status: 400 });
   }
@@ -114,14 +141,16 @@ export async function handleResolve(
         // Hybrid mode: redirect to the JS implementation
         const implPath = resolve(dirname(moduleAbsPath), classDef.$implementation);
         const exportName = xport ?? classDef.title ?? $prototype;
-        const mod = await import(implPath);
-        const ExportedClass = mod[exportName] ?? mod.default?.[exportName];
+        const mod = (await import(implPath)) as ModuleNamespace;
+        const ExportedClass =
+          exportName === undefined ? undefined : (mod[exportName] ?? mod.default?.[exportName]);
         if (typeof ExportedClass !== "function") {
           return new Response(`Export "${exportName}" not found in "${classDef.$implementation}"`, {
             status: 500,
           });
         }
-        const instance = new ExportedClass(config);
+        const ClassCtor = ExportedClass as new (config: unknown) => ClassInstance;
+        const instance = new ClassCtor(config);
         const value =
           typeof instance.resolve === "function"
             ? await instance.resolve()
@@ -165,9 +194,9 @@ export async function handleResolve(
  * @param {string} root
  */
 export async function handleServerFunction(req: Request, root: string) {
-  let body;
+  let body: ServerFunctionBody;
   try {
-    body = await req.json();
+    body = (await req.json()) as ServerFunctionBody;
   } catch {
     return new Response("Invalid JSON body", { status: 400 });
   }
@@ -192,9 +221,9 @@ export async function handleServerFunction(req: Request, root: string) {
     });
   }
 
-  let mod;
+  let mod: ModuleNamespace;
   try {
-    mod = await import(moduleAbsPath);
+    mod = (await import(moduleAbsPath)) as ModuleNamespace;
   } catch (error) {
     return new Response(`Failed to import "${$src}": ${errorMessage(error)}`, {
       status: 500,
@@ -209,7 +238,7 @@ export async function handleServerFunction(req: Request, root: string) {
   }
 
   try {
-    const result = await fn(args);
+    const result = await (fn as (args: Record<string, unknown>) => unknown)(args);
     return Response.json(result ?? null);
   } catch (error) {
     return Response.json({ error: errorMessage(error) }, { status: 500 });

package/src/server.ts

@@ -30,6 +30,14 @@ import { existsSync, readFileSync } from "node:fs";
  * @param {string} urlPath - URL pathname (e.g. "/pages/@jxsuite/parser/Foo.class.json")
  * @returns {string | null} Absolute file path or null
  */
+interface PackageJson {
+  exports?: Record<string, string | { import?: string; default?: string }>;
+  customElements?: string;
+  module?: string;
+  main?: string;
+  [key: string]: unknown;
+}
+
 function resolveNpmPath(rootDir: string, urlPath: string) {
   let root = rootDir;
   let segments = urlPath.split("/").filter(Boolean);
@@ -49,7 +57,7 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
   let start = -1;
   let isScoped = false;
   for (let i = 0; i < segments.length; i++) {
-    if (segments[i].startsWith("@")) {
+    if (segments[i]!.startsWith("@")) {
       start = i;
       isScoped = true;
       break;
@@ -63,14 +71,14 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
     if (start < 0 || start + 1 >= segments.length) {
       return null;
     }
-    const scope = segments[start];
-    const pkg = segments[start + 1];
+    const scope = segments[start]!;
+    const pkg = segments[start + 1]!;
     subpath = segments.slice(start + 2).join("/");
     pkgDir = join(root, "node_modules", scope, pkg);
   } else {
     // Unscoped: try each segment as a package name in node_modules
     for (let i = 0; i < segments.length; i++) {
-      const candidate = join(root, "node_modules", segments[i]);
+      const candidate = join(root, "node_modules", segments[i]!);
       if (existsSync(join(candidate, "package.json"))) {
         start = i;
         pkgDir = candidate;
@@ -91,10 +99,11 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
   // If there's a subpath, check package.json exports first
   if (subpath) {
     try {
-      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as PackageJson;
       const exportKey = `./${subpath}`;
-      if (pkgJson.exports && pkgJson.exports[exportKey]) {
-        const mapped = join(pkgDir, pkgJson.exports[exportKey]);
+      const exportVal = pkgJson.exports?.[exportKey];
+      if (typeof exportVal === "string") {
+        const mapped = join(pkgDir, exportVal);
         if (existsSync(mapped)) {
           return mapped;
         }
@@ -107,7 +116,7 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
     }
     // CEM-relative: subpath may be relative to the custom elements manifest directory
     try {
-      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as PackageJson;
       if (pkgJson.customElements) {
         const cemDir = pkgJson.customElements.replace(/\/[^/]+$/, "");
         const cemRelative = join(pkgDir, cemDir, subpath);
@@ -120,7 +129,7 @@ function resolveNpmPath(rootDir: string, urlPath: string) {
 
   // Bare package (no subpath): resolve entry point
   try {
-    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as PackageJson;
     const exp = pkgJson.exports?.["."];
     const entry =
       (typeof exp === "object" ? (exp.import ?? exp.default) : exp) ??
@@ -236,7 +245,7 @@ export async function createDevServer(options: {
       if (enableStudio && path.startsWith("/__studio/")) {
         // Activate project — tells the server which project root to use for static file fallback
         if (path === "/__studio/activate" && req.method === "POST") {
-          const body = await req.json();
+          const body = (await req.json()) as { root?: string };
           const raw = body.root || null;
           // Always store as absolute path
           activeProjectRoot = raw ? resolve(absRoot, raw) : null;
@@ -265,9 +274,12 @@ export async function createDevServer(options: {
       // Static files
 
       // If the URL path is an absolute filesystem path under the active project, serve directly.
-      // Browsers produce "//abs/path" when an absolute path is used as a URL path — normalise.
-      const fsPath = path.startsWith("//") ? path.slice(1) : path;
-      if (activeProjectRoot && fsPath.startsWith(activeProjectRoot)) {
+      // A POSIX absolute path arrives as "//abs/path"; a Windows one as "/C:/dir/file" (leading
+      // Slash + forward slashes), so drop the slash before the drive letter. Compare with
+      // Separators normalised, since activeProjectRoot is OS-native (backslashes on Windows).
+      const fsPath = path.startsWith("//") ? path.slice(1) : path.replace(/^\/([A-Za-z]:)/, "$1");
+      const normSep = (p: string) => p.replaceAll("\\", "/");
+      if (activeProjectRoot && normSep(fsPath).startsWith(normSep(activeProjectRoot))) {
         const file = Bun.file(fsPath);
         if (await file.exists()) {
           return new Response(file);
@@ -302,7 +314,7 @@ export async function createDevServer(options: {
                 minify: false,
               });
               if (result.success && result.outputs.length > 0) {
-                bundleCache.set(cacheKey, await result.outputs[0].text());
+                bundleCache.set(cacheKey, await result.outputs[0]!.text());
               }
             } catch (error) {
               console.error("Bundle failed for", resolved, error);