@jxsuite/server 1.3.0 → 2.1.0

package/src/refactor/apply.ts

@@ -9,16 +9,14 @@
  */
 
 import { basename, dirname, extname, relative, resolve } from "node:path";
-import { readFile, stat, writeFile } from "node:fs/promises";
+import { stat, writeFile } from "node:fs/promises";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { isUnder } from "./paths.ts";
 import { rewriteDocRefs, rewriteTagName } from "./refs.ts";
+import { documentGlob, fwd, loadDoc, skipScanPath } from "./scan.ts";
 import type { RefChange } from "./refs.ts";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 
-/** Normalise a path to forward slashes. */
-const fwd = (p: string) => p.replaceAll("\\", "/");
-
 export interface FileChange {
   path: string;
   count: number;
@@ -51,20 +49,6 @@ export interface ApplyRenameOptions {
   registry: FormatRegistry;
 }
 
-/** A parsed document plus the serializer that round-trips it back to disk. */
-interface LoadedDoc {
-  doc: unknown;
-  serialize: ((doc: unknown) => Promise<string>) | null;
-}
-
-const isJsonPath = (p: string) => p.endsWith(".json");
-
-/** Skip vendored / build / agent directories (mirrors the component-discovery filter). */
-function skip(match: string): boolean {
-  const f = fwd(match);
-  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
-}
-
 /** Derive a custom-element tag from a component filename (strips `.class.json` or the extension). */
 export function deriveTag(absPath: string): string {
   const base = basename(absPath);
@@ -75,44 +59,6 @@ export function deriveTag(absPath: string): string {
   return ext ? base.slice(0, -ext.length) : base;
 }
 
-/** Read + parse a file, returning the doc and a matching serializer (null when none is available). */
-async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
-  const raw = await readFile(fp, "utf8");
-  if (isJsonPath(fp)) {
-    const trailingNewline = raw.endsWith("\n");
-    return {
-      doc: JSON.parse(raw) as unknown,
-      serialize: (doc) =>
-        Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
-    };
-  }
-  const ext = extname(fp);
-  const parseEntry = registry.byExtension(ext, "parse");
-  if (!parseEntry) {
-    throw new Error(`No parser for "${ext}"`);
-  }
-  const doc = await parseEntry.call("parse", raw);
-  const serializeEntry = registry.byExtension(ext, "serialize");
-  return {
-    doc,
-    serialize: serializeEntry
-      ? async (d) => {
-          const out = await serializeEntry.call("serialize", d);
-          return typeof out === "string" ? out : String(out);
-        }
-      : null,
-  };
-}
-
-/** Build the recursive glob covering JSON plus every registered document/content extension. */
-function documentGlob(registry: FormatRegistry) {
-  const exts = new Set(["json"]);
-  for (const ext of registry.documentExtensions()) {
-    exts.add(ext.replace(/^\./, ""));
-  }
-  return new Bun.Glob(`**/*.{${[...exts].join(",")}}`);
-}
-
 /**
  * Rewrite references (and, for components, the tag) across the project after a rename. The caller
  * must have already moved the file on disk.
@@ -162,7 +108,7 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
   let tagRefsUpdated = 0;
 
   for await (const match of documentGlob(opts.registry).scan({ cwd: opts.root, dot: false })) {
-    if (skip(match)) {
+    if (skipScanPath(match)) {
       continue;
     }
     const fp = fwd(resolve(opts.root, match));

package/src/refactor/index.ts

@@ -5,6 +5,13 @@
 
 export { applyRename, deriveTag } from "./apply.ts";
 export type { ApplyRenameOptions, FileChange, RenameReport } from "./apply.ts";
+export { findReferences, invalidateReferenceCache } from "./find-refs.ts";
+export type {
+  FindReferencesOptions,
+  ReferenceFile,
+  ReferenceHit,
+  ReferencesResult,
+} from "./find-refs.ts";
 export { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
 export type { FsEventPayload } from "./fs-events.ts";
 export { createFsWatcher } from "./watcher.ts";

package/src/refactor/refs.ts

@@ -1,14 +1,21 @@
 /**
- * Refs.ts — pure document reference engine for rename-refactoring.
+ * Refs.ts — pure document reference engine, shared by the rename refactor and the usage query.
  *
- * 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).
+ * One structure-aware walk, two directions. {@link walkDocRefs} dispatches by JSON key and hands
+ * every reference-bearing string to a visitor; whatever the visitor returns is written back, so a
+ * visitor that always returns `null` is a pure reader. Three passes are built on it:
  *
- * 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.
+ * - `rewriteDocRefs` — recompute every file-path reference across a rename (Pillar B).
+ * - `rewriteTagName` — rename a custom-element tag wherever it is used (Pillar C).
+ * - `countTagUses` — the same tag walk, counting instead of writing (the usage query).
+ *
+ * The walk dispatches by JSON key rather than searching strings, 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 (or counted as
+ * a usage) when it actually resolves to the file in question.
+ *
+ * The visitor seam is what stops the read side from being a second, drifting copy of the key list.
+ * A new reference-bearing key added below is a key the usage count sees on the same commit.
  */
 
 import { classifyRef, rewriteRef } from "./paths.ts";
@@ -26,79 +33,74 @@ export interface RewriteResult {
   changes: RefChange[];
 }
 
+/**
+ * One visit of a reference-bearing string.
+ *
+ * @param value — the raw authored reference, exactly as written.
+ * @param refType — which key carried it (`$ref`, `$layout`, `attr`, `imports`, `$elements`, `url`).
+ * @param rootRelativeBare — whether a bare value resolves against the project root (`$layout`).
+ * @returns A replacement string to write back, or `null` to leave the document untouched.
+ */
+export type RefVisitor = (
+  value: string,
+  refType: string,
+  rootRelativeBare: boolean,
+) => string | null;
+
 /** 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(
+/** Offer a scalar string reference under `key` to the visitor, writing back any replacement. */
+function visitScalar(
   container: Record<string, unknown>,
   key: string,
   refType: string,
-  ctx: RemapCtx,
-  changes: RefChange[],
+  visit: RefVisitor,
   rootRelativeBare: boolean,
 ): void {
   const value = container[key];
-  const cls = classifyRef(value);
-  if (cls.kind !== "path") {
+  if (typeof value !== "string") {
     return;
   }
-  const out = rewriteRef(cls, ctx, rootRelativeBare);
+  const out = visit(value, refType, 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 {
+/** Offer a string array member (e.g. an `$elements` entry) to the visitor. */
+function visitIndexed(arr: unknown[], index: number, refType: string, visit: RefVisitor): void {
   const value = arr[index];
-  const cls = classifyRef(value);
-  if (cls.kind !== "path") {
+  if (typeof value !== "string") {
     return;
   }
-  const out = rewriteRef(cls, ctx, false);
+  const out = visit(value, refType, 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 {
+/** Offer every `url(...)` target inside a CSS string to the visitor. */
+function visitUrls(value: string, visit: RefVisitor): 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})`;
+    const out = visit(inner.trim(), "url", false);
+    return out === null ? match : `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 {
+/** Walk a `style` value tree, visiting `url(...)` in every string it contains. */
+function walkStyle(node: unknown, visit: RefVisitor): 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);
+        const out = visitUrls(item, visit);
         if (out !== item) {
           arr[i] = out;
         }
       } else {
-        walkStyle(item, ctx, changes);
+        walkStyle(item, visit);
       }
     }
     return;
@@ -110,21 +112,26 @@ function walkStyle(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
   for (const key of Object.keys(obj)) {
     const value = obj[key];
     if (typeof value === "string") {
-      const out = rewriteUrls(value, ctx, changes);
+      const out = visitUrls(value, visit);
       if (out !== value) {
         obj[key] = out;
       }
     } else {
-      walkStyle(value, ctx, changes);
+      walkStyle(value, visit);
     }
   }
 }
 
-/** Recursive document walk dispatching each reference-bearing key. */
-function walk(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
+/**
+ * Recursive document walk dispatching each reference-bearing key to `visit`.
+ *
+ * This is the single definition of "what counts as a reference" in a Jx document. Mutates `doc`
+ * only where the visitor asks it to.
+ */
+export function walkDocRefs(node: unknown, visit: RefVisitor): void {
   if (Array.isArray(node)) {
     for (const item of node as unknown[]) {
-      walk(item, ctx, changes);
+      walkDocRefs(item, visit);
     }
     return;
   }
@@ -137,28 +144,28 @@ function walk(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
     switch (key) {
       case "$ref": {
         // File-path $ref only; state-scope refs (#/…, $map/…) are filtered by classifyRef.
-        rewriteScalar(obj, key, "$ref", ctx, changes, false);
+        visitScalar(obj, key, "$ref", visit, false);
         break;
       }
       case "$layout": {
-        rewriteScalar(obj, key, "$layout", ctx, changes, true);
+        visitScalar(obj, key, "$layout", visit, true);
         break;
       }
       case "$src":
       case "$implementation": {
-        rewriteScalar(obj, key, key, ctx, changes, false);
+        visitScalar(obj, key, key, visit, false);
         break;
       }
       case "src":
       case "href": {
-        rewriteScalar(obj, key, "attr", ctx, changes, false);
+        visitScalar(obj, key, "attr", visit, 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);
+            visitScalar(imp, name, "imports", visit, false);
           }
         }
         break;
@@ -168,22 +175,22 @@ function walk(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
           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);
+              visitIndexed(els, i, "$elements", visit);
             } else {
-              walk(els[i], ctx, changes);
+              walkDocRefs(els[i], visit);
             }
           }
         } else {
-          walk(value, ctx, changes);
+          walkDocRefs(value, visit);
         }
         break;
       }
       case "style": {
-        walkStyle(value, ctx, changes);
+        walkStyle(value, visit);
         break;
       }
       default: {
-        walk(value, ctx, changes);
+        walkDocRefs(value, visit);
       }
     }
   }
@@ -192,12 +199,31 @@ function walk(node: unknown, ctx: RemapCtx, changes: RefChange[]): void {
 /** 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);
+  walkDocRefs(doc, (value, refType, rootRelativeBare) => {
+    const cls = classifyRef(value);
+    if (cls.kind !== "path") {
+      return null;
+    }
+    const out = rewriteRef(cls, ctx, rootRelativeBare);
+    if (out === null) {
+      return null;
+    }
+    changes.push({ from: value, refType, to: out });
+    return out;
+  });
   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 {
+/**
+ * Recursive tag walk. With `newTag` set, every `tagName === oldTag` is rewritten; with `newTag`
+ * null, they are only counted — the read side of the same traversal.
+ */
+function walkTags(
+  node: unknown,
+  oldTag: string,
+  newTag: string | null,
+  counter: { n: number },
+): void {
   if (Array.isArray(node)) {
     for (const item of node as unknown[]) {
       walkTags(item, oldTag, newTag, counter);
@@ -209,7 +235,9 @@ function walkTags(node: unknown, oldTag: string, newTag: string, counter: { n: n
   }
   const obj = node as Record<string, unknown>;
   if (obj.tagName === oldTag) {
-    obj.tagName = newTag;
+    if (newTag !== null) {
+      obj.tagName = newTag;
+    }
     counter.n += 1;
   }
   for (const key of Object.keys(obj)) {
@@ -234,3 +262,15 @@ export function rewriteTagName(
   }
   return { count: counter.n, doc };
 }
+
+/**
+ * How many nodes in `doc` carry `tagName === tag`. Read-only; `doc` is never touched.
+ *
+ * A component's OWN definition file answers 1 for its root node, which is why the usage query skips
+ * the definition file rather than subtracting one — a component may legitimately nest itself.
+ */
+export function countTagUses(doc: unknown, tag: string): number {
+  const counter = { n: 0 };
+  walkTags(doc, tag, null, counter);
+  return counter.n;
+}

package/src/refactor/scan.ts

@@ -0,0 +1,70 @@
+/**
+ * Scan.ts — the project document sweep the refactor engines share.
+ *
+ * `applyRename` (write pass) and `findReferences` (read pass) walk exactly the same file set: every
+ * JSON document plus every extension the project's format registry claims, minus the vendored /
+ * build / agent directories. Keeping one definition of "the project's documents" is the point — a
+ * rename that rewrites a file the usage count never looked at is a lie in both directions.
+ */
+
+import { extname } from "node:path";
+import { readFile } from "node:fs/promises";
+import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+
+/** Normalise a path to forward slashes (Windows `path` returns backslashes). */
+export const fwd = (p: string) => p.replaceAll("\\", "/");
+
+/** A parsed document plus the serializer that round-trips it back to disk (null when none). */
+export interface LoadedDoc {
+  doc: unknown;
+  serialize: ((doc: unknown) => Promise<string>) | null;
+}
+
+const isJsonPath = (p: string) => p.endsWith(".json");
+
+/** Skip vendored / build / agent directories (mirrors the component-discovery filter). */
+export function skipScanPath(match: string): boolean {
+  const f = fwd(match);
+  return match.includes("node_modules") || f.includes("dist/") || f.includes(".claude/");
+}
+
+/** Build the recursive glob covering JSON plus every registered document/content extension. */
+export function documentGlob(registry: FormatRegistry): Bun.Glob {
+  const exts = new Set(["json"]);
+  for (const ext of registry.documentExtensions()) {
+    exts.add(ext.replace(/^\./, ""));
+  }
+  return new Bun.Glob(`**/*.{${[...exts].join(",")}}`);
+}
+
+/**
+ * Read + parse a file, returning the doc and a matching serializer (null when the format can parse
+ * but not serialize). Throws when no parser claims the extension.
+ */
+export async function loadDoc(fp: string, registry: FormatRegistry): Promise<LoadedDoc> {
+  const raw = await readFile(fp, "utf8");
+  if (isJsonPath(fp)) {
+    const trailingNewline = raw.endsWith("\n");
+    return {
+      doc: JSON.parse(raw) as unknown,
+      serialize: (doc) =>
+        Promise.resolve(JSON.stringify(doc, null, 2) + (trailingNewline ? "\n" : "")),
+    };
+  }
+  const ext = extname(fp);
+  const parseEntry = registry.byExtension(ext, "parse");
+  if (!parseEntry) {
+    throw new Error(`No parser for "${ext}"`);
+  }
+  const doc = await parseEntry.call("parse", raw);
+  const serializeEntry = registry.byExtension(ext, "serialize");
+  return {
+    doc,
+    serialize: serializeEntry
+      ? async (d) => {
+          const out = await serializeEntry.call("serialize", d);
+          return typeof out === "string" ? out : String(out);
+        }
+      : null,
+  };
+}

package/src/refactor/watcher.ts

@@ -8,6 +8,7 @@
 
 import { watch as chokidarWatch } from "chokidar";
 import { coalesceFsEvents, toFsEvent } from "./fs-events.ts";
+import { invalidateReferenceCache } from "./find-refs.ts";
 import type { FsEventPayload } from "./fs-events.ts";
 
 const IGNORE_SEGMENTS = ["node_modules", ".git", "dist", ".jx", ".direnv", ".devenv"];
@@ -45,6 +46,9 @@ export function createFsWatcher(
     if (!event) {
       return;
     }
+    // Any move under the root can change who references what, so the usage cache drops the whole
+    // Project rather than trying to derive which queries this one path could have affected.
+    invalidateReferenceCache(root);
     buffer = coalesceFsEvents(buffer, event);
     if (timer) {
       clearTimeout(timer);

package/src/resolve.ts

@@ -11,6 +11,7 @@ import { loadAssetMounts } from "@jxsuite/compiler/asset-mounts";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { DynamicClass } from "@jxsuite/runtime/types";
 import type { JxClassDef, ProjectConfig } from "@jxsuite/schema/types";
+import { problem } from "./problem.ts";
 
 interface ModuleNamespace {
   default?: Record<string, unknown>;
@@ -126,12 +127,12 @@ export async function handleResolve(
   try {
     body = (await req.json()) as ResolveBody;
   } catch {
-    return new Response("Invalid JSON body", { status: 400 });
+    return problem("invalidRequest", "Invalid JSON body");
   }
 
   const { $src, $prototype, $export: xport, $base, ...config } = body;
   if (!$src) {
-    return new Response("Missing $src", { status: 400 });
+    return problem("invalidRequest", "Missing $src");
   }
 
   let moduleAbsPath;
@@ -200,7 +201,7 @@ export async function handleResolve(
         // A trusted (bare-specifier) class file names its own sibling implementation; only a
         // Project-local relative $src is held to the root-escape guard.
         if (!trustedResolution && !isImportable(implPath, root, activeProjectRoot)) {
-          return new Response(`$implementation escapes the project root`, { status: 403 });
+          return problem("pathOutsideProject", "$implementation escapes the project root");
         }
         const exportName = xport ?? classDef.title ?? $prototype;
         const mod = (await import(implPath)) as ModuleNamespace;
@@ -236,7 +237,7 @@ export async function handleResolve(
             : instance;
       return Response.json(value);
     } catch (error) {
-      return Response.json({ error: errorMessage(error) }, { status: 500 });
+      return problem("internalError", errorMessage(error));
     }
   }
 
@@ -260,12 +261,12 @@ export async function handleServerFunction(req: Request, root: string) {
   try {
     body = (await req.json()) as ServerFunctionBody;
   } catch {
-    return new Response("Invalid JSON body", { status: 400 });
+    return problem("invalidRequest", "Invalid JSON body");
   }
 
   const { $src, $export: xport, $base, arguments: args = {} } = body;
   if (!$src || !xport) {
-    return new Response("Missing $src or $export", { status: 400 });
+    return problem("invalidRequest", "Missing $src or $export");
   }
 
   let moduleAbsPath;
@@ -278,9 +279,7 @@ export async function handleServerFunction(req: Request, root: string) {
       moduleAbsPath = resolve(root, $src);
     }
   } catch (error) {
-    return new Response(`Cannot resolve $src: ${errorMessage(error)}`, {
-      status: 400,
-    });
+    return problem("invalidRequest", `Cannot resolve $src: ${errorMessage(error)}`);
   }
 
   if (!isImportable(moduleAbsPath, root, null)) {
@@ -312,7 +311,7 @@ export async function handleServerFunction(req: Request, root: string) {
     );
     return Response.json(result ?? null);
   } catch (error) {
-    return Response.json({ error: errorMessage(error) }, { status: 500 });
+    return problem("internalError", errorMessage(error));
   }
 }