@jxsuite/server 2.0.0 → 2.2.1

package/src/project-server.ts

@@ -26,6 +26,7 @@
  */
 
 import { resolve, sep } from "node:path";
+import type { ServerWebSocket } from "bun";
 import { handleJxMounts } from "./jx-mounts.ts";
 import { handleResolve, handleServerFunction, projectAssetMounts } from "./resolve.ts";
 import { handleAiApi } from "./ai-api.ts";
@@ -35,9 +36,13 @@ import type { ImportApiOptions } from "./import-api.ts";
 import {
   decodeAndNormalizePath,
   loopbackGate,
+  originHostGate,
   serveContained,
   serveProjectFile,
 } from "./net-guard.ts";
+import { problem } from "./problem.ts";
+import { createLoopbackAuthorizer, OAUTH_CALLBACK_PATH } from "./oauth-loopback.ts";
+import type { LoopbackAuthorizer } from "./oauth-loopback.ts";
 
 /** A resolved per-window session: its project root plus its RPC handler map. */
 export interface ProjectServerSession {
@@ -73,6 +78,23 @@ export interface ProjectServerHandle {
   wsUrl: string;
   rpcToken: string;
   canvasUrl: string;
+  /**
+   * Push an UNSOLICITED message to the connected shells — the server-to-client half of the RPC.
+   *
+   * Every other frame on this socket answers an `id` the client chose; these carry a `method` and
+   * no `id`, which is how the client's dispatcher tells the two apart. It exists because some
+   * things the shell must know are not answers to anything it asked: a file changed on disk, or
+   * another window wants this one raised.
+   *
+   * @param winId Deliver only to sockets stashed with this window id; omit for every socket.
+   * @returns How many sockets the message reached — 0 means nothing is listening yet.
+   */
+  push: (method: string, params?: unknown, winId?: string | null) => number;
+  /**
+   * The RFC 8252 loopback authorization host. The desktop launcher drives it: `begin()` for the URL
+   * to open in the user's browser, then `await pending.code` and {@link exchangeCode}.
+   */
+  authorizer: LoopbackAuthorizer;
   stop: () => void;
 }
 
@@ -94,6 +116,14 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
   // Bundle cache for npm bare specifiers (mirrors server.ts).
   const bundleCache = new Map<string, string>();
 
+  /* Outstanding OAuth authorizations (RFC 8252). Per server, so a stopped server abandons them. */
+  const authorizer: LoopbackAuthorizer = createLoopbackAuthorizer();
+
+  /* Live shell sockets, so the server can speak first (see ProjectServerHandle.push). Membership is
+     the socket's whole lifetime — added on open, dropped on close — so a push after a window is
+     gone reaches nobody rather than throwing. */
+  const sockets = new Set<ServerWebSocket<{ winId: string | null }>>();
+
   const server = Bun.serve<{ winId: string | null }>({
     hostname,
     port,
@@ -111,6 +141,30 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
 
       const winId = url.searchParams.get("win");
 
+      /*
+       * 0. The OAuth loopback redirect (RFC 8252 §7.3).
+       *
+       *    **Exempt from the token, and only from the token.** The provider redirects the user's
+       *    own browser here; that navigation carries whatever the provider's `redirect_uri` said,
+       *    and a page cannot append a secret to a URL it does not compose. Gating it on the token
+       *    would make the flow impossible rather than safe.
+       *
+       *    What replaces the token is the `state` parameter, which is unguessable, single-use and
+       *    compared in constant time — plus the Host and Fetch Metadata checks, which still apply.
+       *    An IdP redirect is exactly the one cross-site shape the strict policy admits: a
+       *    top-level GET document navigation, a person following a link.
+       */
+      if (normPath === OAUTH_CALLBACK_PATH) {
+        const gate = originHostGate(req, "strict");
+        if (gate) {
+          return gate;
+        }
+        const callback = authorizer.handleCallback(url);
+        if (callback) {
+          return callback;
+        }
+      }
+
       // 1. WebSocket upgrade — token + loopback Origin/Host are the hard gate.
       const upgrade = req.headers.get("upgrade");
       if (upgrade && upgrade.toLowerCase() === "websocket") {
@@ -121,11 +175,20 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         if (srv.upgrade(req, { data: { winId } })) {
           return;
         }
-        return new Response("Upgrade failed", { status: 400 });
+        return problem("invalidRequest", "Upgrade failed");
       }
 
-      // 2. AI SSE — keep the existing handleAiApi behavior (rewrite the studio-ai prefix).
+      /*
+       * 2. AI proxy. Gated with the token, like every other surface that spends something: this
+       *    route forwards to a provider on the user's key, so an ungated one is an open relay for
+       *    any local process — and it was dispatched ahead of every gate. The token is what the
+       *    desktop shell appends to this URL; a request without one is refused.
+       */
       if (normPath.startsWith("/__studio__/ai/")) {
+        const gate = loopbackGate(req, url, rpcToken);
+        if (gate) {
+          return gate;
+        }
         const aiUrl = new URL(req.url);
         aiUrl.pathname = normPath.replace("/__studio__/ai/", "/__studio/ai/");
         const aiResponse = await handleAiApi(req, aiUrl);
@@ -139,7 +202,7 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
       if (normPath === "/__studio__/import-site" && req.method === "POST") {
         const { importApi } = options;
         if (!importApi) {
-          return new Response("Not found", { status: 404 });
+          return problem("notFound", "Not found");
         }
         const gate = loopbackGate(req, url, rpcToken);
         if (gate) {
@@ -168,22 +231,34 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
           headers.set("Referrer-Policy", "same-origin");
           return new Response(res.body, { headers, status: res.status });
         }
-        return new Response("Not found", { status: 404 });
+        return problem("notFound", "Not found");
       }
 
       // 4. Resolve the session (fail-closed).
       const session = resolveSession(winId);
       if (!session) {
-        return new Response("Unknown window", { status: 404 });
+        return problem("notFound", "Unknown window");
       }
       const root = session.projectRoot;
       if (!root) {
-        return new Response("No project", { status: 404 });
+        return problem("notFound", "No project");
       }
 
-      // 4b. Extension server mounts (/_jx/data etc.) — registry-driven, same wire contract as
-      //     The generated site worker and the dev server (specs/extensions.md §11).
+      /*
+       * 4b. Extension server mounts (/_jx/data etc.) — registry-driven, same wire contract as the
+       *     generated site worker and the dev server (specs/extensions.md §11).
+       *
+       *     Gated on **Origin/Host and Fetch Metadata, not the token**, and the distinction is the
+       *     point: these are fetched by the canvas iframe's own page, whose requests carry no
+       *     `?token=` — a page cannot rewrite the URLs its own content asks for. So the token is
+       *     the wrong instrument here and the origin check is the right one. The policy is
+       *     `embeddable` because that iframe is cross-origin by construction.
+       */
       if (normPath.startsWith("/_jx/")) {
+        const gate = originHostGate(req, "embeddable");
+        if (gate) {
+          return gate;
+        }
         const mountRes = await handleJxMounts(req, url, root);
         if (mountRes) {
           return mountRes;
@@ -206,8 +281,17 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         return handleServerFunction(req, root);
       }
 
-      // 6. Project files at natural URLs, including extension asset mounts (§8.5) — that is what
-      // Lets a canvas preview show an image a content entry references relative to itself.
+      /*
+       * 6. Project files at natural URLs, including extension asset mounts (§8.5) — that is what
+       *    lets a canvas preview show an image a content entry references relative to itself.
+       *
+       *    `embeddable`, for the same reason as the mounts: these ARE the canvas iframe's
+       *    subresources, and a cross-origin iframe's images arrive `cross-site`.
+       */
+      const staticGate = originHostGate(req, "embeddable");
+      if (staticGate) {
+        return staticGate;
+      }
       const fileRes = await serveProjectFile(normPath, root, await projectAssetMounts(root));
       if (fileRes) {
         return fileRes;
@@ -238,10 +322,20 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         }
       }
 
-      return new Response("Not found", { status: 404 });
+      /* 8. The project's BUILT SITE is not served here — see the same note in `server.ts`. This
+         server's paths mean the project's SOURCES, and a built page means its own output by the
+         very same paths; `site-preview.ts` gives that output its own origin, which is what
+         `View: Open in Browser` opens. */
+      return problem("notFound", "Not found");
     },
 
     websocket: {
+      open(ws) {
+        sockets.add(ws);
+      },
+      close(ws) {
+        sockets.delete(ws);
+      },
       async message(ws, raw) {
         let msg: { id: number; method: string; params?: unknown };
         try {
@@ -291,7 +385,26 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
     wsUrl,
     rpcToken,
     canvasUrl,
+    authorizer,
+    push: (method, params, winId) => {
+      const frame = JSON.stringify(params === undefined ? { method } : { method, params });
+      let delivered = 0;
+      for (const ws of sockets) {
+        if (winId !== undefined && winId !== null && ws.data.winId !== winId) {
+          continue;
+        }
+        try {
+          ws.send(frame);
+          delivered += 1;
+        } catch {
+          // A socket that closed between the iteration and the send is simply not a recipient.
+        }
+      }
+      return delivered;
+    },
     stop: () => {
+      // Abandon outstanding sign-ins first: their callbacks can no longer arrive.
+      authorizer.stop();
       void server.stop(true);
     },
   };

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;
+}