@jxsuite/server 4.5.0 → 4.5.1

package/src/packages.ts

@@ -8,42 +8,23 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-
-export interface PackageInfo {
-  name: string;
-  version: string;
-  /** True when the dependency lives in `devDependencies` rather than `dependencies`. */
-  dev?: boolean;
-}
-
-/**
- * A dependency's pinned range beside the newest version published for it on the registry.
- *
- * Every registry-range dependency gets a row, behind or not. Deciding whether a row is an upgrade
- * needs a semver comparison against the range's base, and the caller — which has to make that
- * comparison anyway to tell an upgrade from a project deliberately pinned ahead — is where it
- * belongs. A backend that filtered here could only describe an up-to-date package as an absence.
- */
-export interface PackageVersionInfo {
-  name: string;
-  /** The version range pinned in package.json (e.g. "^0.19.0"). */
-  current: string;
-  /** The newest version published for this package on the registry. */
-  latest: string;
-  dev?: boolean;
-}
-
-/** Result of a package mutation that runs `bun install` (install / set-versions). */
-export interface PackageOpResult {
-  ok: boolean;
-  /** Combined stdout/stderr from the bun invocation, surfaced to the user on failure. */
-  log?: string;
-}
-
+import type { PackageInfo, PackageOpResult, PackageVersionInfo } from "@jxsuite/protocol";
+import type { JsonValue } from "@jxsuite/schema/types";
+
+/* The package rows and operation result are the Studio wire contract (`packages*` routes), declared
+   once in @jxsuite/protocol; re-exported so this module's public names stay. Every
+   registry-range dependency gets a `PackageVersionInfo` row, behind or not: deciding whether a row
+   is an upgrade needs a semver comparison against the range's base, and the caller, which has to
+   make that comparison anyway to tell an upgrade from a project deliberately pinned ahead, is where
+   it belongs. A backend that filtered here could only describe an up-to-date package as an
+   absence. */
+export type { PackageInfo, PackageOpResult, PackageVersionInfo } from "@jxsuite/protocol";
+
+/** The manifest members this module edits; every other member is written back unchanged. */
 interface PackageJson {
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
-  [key: string]: unknown;
+  [key: string]: JsonValue | undefined;
 }
 
 /** Minimal fetch signature (injectable for tests; the global `fetch` satisfies it). */
@@ -72,6 +53,9 @@ async function readPackageJson(root: string): Promise<PackageJson | null> {
     return null;
   }
   try {
+    /* SAFETY: package.json is the npm manifest `bun install` reads, an object whose
+       `dependencies`/`devDependencies` map package names to version-spec strings; text that is
+       not JSON throws into the catch below. */
     return JSON.parse(await readFile(pkgPath, "utf8")) as PackageJson;
   } catch {
     return null;
@@ -120,7 +104,11 @@ async function runBun(args: string[], cwd: string): Promise<PackageOpResult> {
     proc.exited,
   ]);
   const log = `${stdout}${stderr}`.trim();
-  return { ok: exitCode === 0, ...(log ? { log } : {}) };
+  const result: PackageOpResult = { ok: exitCode === 0 };
+  if (log) {
+    result.log = log;
+  }
+  return result;
 }
 
 /** Run `bun install` in the project root. */
@@ -165,6 +153,8 @@ export async function fetchLatestVersion(
     if (!res.ok) {
       return null;
     }
+    /* SAFETY: the registry's version endpoint answers that version's manifest, whose `version`
+       is a string; a body that is not JSON (or is `null`) throws into the catch, giving null. */
     const data = (await res.json()) as { version?: string };
     return data.version ?? null;
   } catch {
@@ -228,6 +218,7 @@ export async function setPackageVersions(
   }
   let pkg: PackageJson;
   try {
+    // SAFETY: same npm manifest contract as readPackageJson; unparseable text is caught below.
     pkg = JSON.parse(await readFile(pkgPath, "utf8")) as PackageJson;
   } catch (error) {
     return { log: `Unparseable package.json: ${String(error)}`, ok: false };
@@ -239,8 +230,7 @@ export async function setPackageVersions(
       pkg.dependencies[update.name] = update.version;
     } else {
       const bucket = update.dev ? "devDependencies" : "dependencies";
-      pkg[bucket] = { ...(pkg[bucket] as Record<string, string> | undefined) };
-      (pkg[bucket] as Record<string, string>)[update.name] = update.version;
+      pkg[bucket] = { ...pkg[bucket], [update.name]: update.version };
     }
   }
   await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");

package/src/problem.ts

@@ -13,6 +13,7 @@
 
 import { PROBLEM_MEDIA_TYPE, problemDetails } from "@jxsuite/protocol";
 import type { ProblemTypeName } from "@jxsuite/protocol";
+import type { JsonObject } from "@jxsuite/schema/types";
 
 /**
  * A failure response for one occurrence of a declared problem type.
@@ -23,14 +24,10 @@ import type { ProblemTypeName } from "@jxsuite/protocol";
  *
  * @param {ProblemTypeName} name - A declared type from `PROBLEM_TYPES`
  * @param {string} [detail] - What happened this time; the line a human reads
- * @param {Record<string, unknown>} [extensions] - Extension members this type documents
+ * @param {JsonObject} [extensions] - Extension members this type documents
  * @returns {Response}
  */
-export function problem(
-  name: ProblemTypeName,
-  detail?: string,
-  extensions?: Record<string, unknown>,
-): Response {
+export function problem(name: ProblemTypeName, detail?: string, extensions?: JsonObject): Response {
   const body = problemDetails(name, detail, extensions);
   // The explicit Content-Type is the point: `Response.json` would send `application/json`, and
   // RFC 9457 §3 is what tells a client this body is a problem rather than a result.

package/src/project-server.ts

@@ -43,11 +43,36 @@ import {
 import { problem } from "./problem.ts";
 import { createLoopbackAuthorizer, OAUTH_CALLBACK_PATH } from "./oauth-loopback.ts";
 import type { LoopbackAuthorizer } from "./oauth-loopback.ts";
+import type { FsEventBatch } from "./sse.ts";
+import type { JsonPrimitive, JsonValue } from "@jxsuite/schema/types";
+
+/**
+ * What a handler answers, sent as the reply frame's `result`: anything `JSON.stringify` encodes,
+ * with `undefined` sent as `null`. Objects are admitted by kind rather than by JSON shape because
+ * handlers answer with typed values, and TypeScript never treats an interface as a `JsonValue`.
+ */
+export type RpcResult = JsonPrimitive | object | undefined;
+
+/** One RPC method: the request frame's decoded `params` in, the reply's `result` out. */
+export type RpcHandler = (params: JsonValue | undefined) => Promise<RpcResult>;
+
+/**
+ * What an unsolicited push carries as its `params`: JSON, or the filesystem batch the sidebar
+ * consumes (the same batch the dev server sends as its SSE `fs` event).
+ */
+export type RpcPushParams = JsonValue | FsEventBatch;
+
+/** An RPC request frame as the shell sends it: the id the reply echoes, and what to dispatch. */
+export interface RpcRequestFrame {
+  id: number;
+  method: string;
+  params?: JsonValue;
+}
 
 /** A resolved per-window session: its project root plus its RPC handler map. */
 export interface ProjectServerSession {
   projectRoot: string | null;
-  handlers: Record<string, (params: unknown) => Promise<unknown>>;
+  handlers: Record<string, RpcHandler>;
 }
 
 export interface CreateProjectServerOptions {
@@ -89,7 +114,7 @@ export interface ProjectServerHandle {
    * @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;
+  push: (method: string, params?: RpcPushParams, 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}.
@@ -337,9 +362,14 @@ export function createProjectServer(options: CreateProjectServerOptions): Projec
         sockets.delete(ws);
       },
       async message(ws, raw) {
-        let msg: { id: number; method: string; params?: unknown };
+        let msg: RpcRequestFrame;
         try {
-          msg = JSON.parse(raw as string) as { id: number; method: string; params?: unknown };
+          /* SAFETY: trust boundary. A binary frame decodes as UTF-8, exactly as JSON.parse's own
+             string coercion would, and the parse yields a JSON value. The only client on this
+             token-gated socket is the shell's RPC transport, which sends `{ id, method, params }`;
+             a frame that breaks that finds no handler under its `method` and is answered with an
+             error (a `null` frame throws in this callback, as it always has). */
+          msg = JSON.parse(raw.toString()) as RpcRequestFrame;
         } catch {
           ws.send(JSON.stringify({ error: "Invalid JSON", id: 0 }));
           return;

package/src/refactor/apply.ts

@@ -10,6 +10,7 @@
 
 import { basename, dirname, extname, relative, resolve } from "node:path";
 import { stat, writeFile } from "node:fs/promises";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { isUnder } from "./paths.ts";
 import { rewriteDocRefs, rewriteTagName } from "./refs.ts";
@@ -99,9 +100,9 @@ export async function applyRename(opts: ApplyRenameOptions): Promise<RenameRepor
   if (!isDir) {
     try {
       const { doc } = await loadDoc(absTo, opts.registry);
-      const oldTag = (doc as { tagName?: unknown }).tagName;
+      const oldTag = isJsonObject(doc) ? doc.tagName : undefined;
       const newTag = deriveTag(absTo);
-      if (typeof oldTag === "string" && oldTag.includes("-") && newTag !== oldTag) {
+      if (isString(oldTag) && oldTag.includes("-") && newTag !== oldTag) {
         if (newTag.includes("-")) {
           tagRename = { from: oldTag, to: newTag };
         } else {

package/src/refactor/fs-events.ts

@@ -5,26 +5,25 @@
  */
 
 import { relative } from "node:path";
+import type { FsEvent } from "@jxsuite/protocol";
 
-/** A filesystem change as broadcast to the studio shell (root-relative, forward-slashed path). */
-export interface FsEventPayload {
-  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
-  path: string;
-  isDir: boolean;
-}
+/* A filesystem change as broadcast to the studio shell is the protocol's `FsEvent`, declared once
+   there; `FsEventPayload` stays this module's public name for it. */
+export type { FsEvent as FsEventPayload } from "@jxsuite/protocol";
+
+const VALID: ReadonlySet<string> = new Set(["add", "change", "unlink", "addDir", "unlinkDir"]);
 
-const VALID = new Set(["add", "change", "unlink", "addDir", "unlinkDir"]);
+/** Whether chokidar's `eventType` is one of the five changes the sidebar is told about. */
+function isFsEventType(eventType: string): eventType is FsEvent["type"] {
+  return VALID.has(eventType);
+}
 
 /**
  * Map one chokidar event to a payload, or null for events we ignore (`ready`/`raw`/`error`) or
  * paths that escape the root.
  */
-export function toFsEvent(
-  eventType: string,
-  root: string,
-  changedPath: string,
-): FsEventPayload | null {
-  if (!VALID.has(eventType)) {
+export function toFsEvent(eventType: string, root: string, changedPath: string): FsEvent | null {
+  if (!isFsEventType(eventType)) {
     return null;
   }
   const path = relative(root, changedPath).replaceAll("\\", "/");
@@ -34,7 +33,7 @@ export function toFsEvent(
   return {
     isDir: eventType === "addDir" || eventType === "unlinkDir",
     path,
-    type: eventType as FsEventPayload["type"],
+    type: eventType,
   };
 }
 
@@ -42,7 +41,7 @@ export function toFsEvent(
  * Fold one event into a buffer, collapsing redundant churn per path (last-write-wins, except
  * add+unlink cancels, add+change stays add, and unlink+add becomes a re-add). Returns a new array.
  */
-export function coalesceFsEvents(buffer: FsEventPayload[], next: FsEventPayload): FsEventPayload[] {
+export function coalesceFsEvents(buffer: FsEvent[], next: FsEvent): FsEvent[] {
   const prev = buffer.find((e) => e.path === next.path);
   if (!prev) {
     return [...buffer, next];

package/src/refactor/paths.ts

@@ -19,6 +19,8 @@
 
 import { BUILD_LANES, projectPathsForSiteUrl, siteUrlForPath } from "@jxsuite/schema/asset-paths";
 import type { AssetLane, AssetMount } from "@jxsuite/schema/asset-paths";
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 /**
  * The lanes a rewritten site URL is re-emitted through, most-publishable first.
@@ -43,6 +45,12 @@ const AUTHORED_LANES: readonly AssetLane[] = [...BUILD_LANES, "root"];
  */
 const READ_LANES: readonly AssetLane[] = ["mounts", "root", "public"];
 
+/** A path-like value split at its first `?` or `#`: the path itself, and what trails it. */
+export interface RefParts {
+  core: string;
+  suffix: string;
+}
+
 /** Classification of a reference string value. */
 export type RefClass =
   | { kind: "none" }
@@ -51,7 +59,7 @@ export type RefClass =
   | { kind: "path"; core: string; suffix: string; rooted: boolean };
 
 /** Split a trailing `?query` or `#fragment` off a path-like value. */
-export function splitQueryHash(value: string): { core: string; suffix: string } {
+export function splitQueryHash(value: string): RefParts {
   for (let i = 0; i < value.length; i += 1) {
     const ch = value[i];
     if (ch === "?" || ch === "#") {
@@ -68,8 +76,8 @@ export function splitQueryHash(value: string): { core: string; suffix: string }
  * actual precision, so bare npm specifiers (which never resolve to the renamed file) are simply
  * never matched.
  */
-export function classifyRef(value: unknown): RefClass {
-  if (typeof value !== "string" || value.length === 0) {
+export function classifyRef(value: JsonValue | undefined): RefClass {
+  if (!isString(value) || value.length === 0) {
     return { kind: "none" };
   }
   if (

package/src/refactor/refs.ts

@@ -26,6 +26,8 @@
  * @docs studio/projects/pages-layouts-components
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 import { classifyRef, looksLikeFileRef, rewriteRef } from "./paths.ts";
 import type { RemapCtx } from "./paths.ts";
 
@@ -37,10 +39,16 @@ export interface RefChange {
 }
 
 export interface RewriteResult {
-  doc: unknown;
+  doc: JsonValue;
   changes: RefChange[];
 }
 
+/** The outcome of {@link rewriteTagName}: the same document, and how many nodes were renamed. */
+export interface TagRewriteResult {
+  doc: JsonValue;
+  count: number;
+}
+
 /**
  * One visit of a reference-bearing string.
  *
@@ -74,14 +82,14 @@ const PROSE_KEYS = new Set(["textContent", "innerHTML"]);
 
 /** Offer a scalar string reference under `key` to the visitor, writing back any replacement. */
 function visitScalar(
-  container: Record<string, unknown>,
+  container: JsonObject,
   key: string,
   refType: string,
   visit: RefVisitor,
   rootRelativeBare: boolean,
 ): void {
   const value = container[key];
-  if (typeof value !== "string") {
+  if (!isString(value)) {
     return;
   }
   const out = visit(value, refType, rootRelativeBare);
@@ -104,13 +112,13 @@ function visitScalar(
  * would.
  */
 function visitKeys(
-  container: Record<string, unknown>,
+  container: JsonObject,
   refType: string,
   visit: RefVisitor,
   rootRelativeBare: boolean,
 ): void {
   const entries = Object.entries(container);
-  const renamed = entries.map(([key, value]): [string, unknown] => {
+  const renamed = entries.map(([key, value]): [string, JsonValue] => {
     const out = visit(key, refType, rootRelativeBare);
     return [out === null ? key : out, value];
   });
@@ -126,9 +134,9 @@ function visitKeys(
 }
 
 /** Offer a string array member (e.g. an `$elements` entry) to the visitor. */
-function visitIndexed(arr: unknown[], index: number, refType: string, visit: RefVisitor): void {
+function visitIndexed(arr: JsonValue[], index: number, refType: string, visit: RefVisitor): void {
   const value = arr[index];
-  if (typeof value !== "string") {
+  if (!isString(value)) {
     return;
   }
   const out = visit(value, refType, false);
@@ -146,15 +154,14 @@ function visitUrls(value: string, visit: RefVisitor): string {
 }
 
 /** Walk a `style` value tree, visiting `url(...)` in every string it contains. */
-function walkStyle(node: unknown, visit: RefVisitor): void {
+function walkStyle(node: JsonValue | undefined, 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") {
+    for (let i = 0; i < node.length; i += 1) {
+      const item = node[i];
+      if (isString(item)) {
         const out = visitUrls(item, visit);
         if (out !== item) {
-          arr[i] = out;
+          node[i] = out;
         }
       } else {
         walkStyle(item, visit);
@@ -162,16 +169,15 @@ function walkStyle(node: unknown, visit: RefVisitor): void {
     }
     return;
   }
-  if (!node || typeof node !== "object") {
+  if (!isJsonObject(node)) {
     return;
   }
-  const obj = node as Record<string, unknown>;
-  for (const key of Object.keys(obj)) {
-    const value = obj[key];
-    if (typeof value === "string") {
+  for (const key of Object.keys(node)) {
+    const value = node[key];
+    if (isString(value)) {
       const out = visitUrls(value, visit);
       if (out !== value) {
-        obj[key] = out;
+        node[key] = out;
       }
     } else {
       walkStyle(value, visit);
@@ -185,56 +191,53 @@ function walkStyle(node: unknown, visit: RefVisitor): void {
  * 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 {
+export function walkDocRefs(node: JsonValue | undefined, visit: RefVisitor): void {
   if (Array.isArray(node)) {
-    for (const item of node as unknown[]) {
+    for (const item of node) {
       walkDocRefs(item, visit);
     }
     return;
   }
-  if (!node || typeof node !== "object") {
+  if (!isJsonObject(node)) {
     return;
   }
-  const obj = node as Record<string, unknown>;
-  for (const key of Object.keys(obj)) {
-    const value = obj[key];
+  for (const key of Object.keys(node)) {
+    const value = node[key];
     switch (key) {
       case "$ref": {
         // File-path $ref only; state-scope refs (#/…, $map/…) are filtered by classifyRef.
-        visitScalar(obj, key, "$ref", visit, false);
+        visitScalar(node, key, "$ref", visit, false);
         break;
       }
       case "$layout": {
-        visitScalar(obj, key, "$layout", visit, true);
+        visitScalar(node, key, "$layout", visit, true);
         break;
       }
       case "$src":
       case "$implementation": {
-        visitScalar(obj, key, key, visit, false);
+        visitScalar(node, key, key, visit, false);
         break;
       }
       case "src":
       case "href": {
-        visitScalar(obj, key, "attr", visit, false);
+        visitScalar(node, 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)) {
-            visitScalar(imp, name, "imports", visit, false);
+        if (isJsonObject(value)) {
+          for (const name of Object.keys(value)) {
+            visitScalar(value, name, "imports", visit, 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") {
-              visitIndexed(els, i, "$elements", visit);
+          for (let i = 0; i < value.length; i += 1) {
+            if (isString(value[i])) {
+              visitIndexed(value, i, "$elements", visit);
             } else {
-              walkDocRefs(els[i], visit);
+              walkDocRefs(value[i], visit);
             }
           }
         } else {
@@ -255,8 +258,8 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
          * renaming a file at the project root could rewrite an unrelated copy DESTINATION that
          * merely shared its name.
          */
-        if (value && typeof value === "object" && !Array.isArray(value)) {
-          visitKeys(value as Record<string, unknown>, "copy", visit, true);
+        if (isJsonObject(value)) {
+          visitKeys(value, "copy", visit, true);
         }
         break;
       }
@@ -272,7 +275,7 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
          * resolve-and-compare gate, which only matches a value resolving to the file or directory
          * in question. A remote `https://…` source is filtered by `classifyRef` before that.
          */
-        visitScalar(obj, key, "source", visit, false);
+        visitScalar(node, key, "source", visit, false);
         break;
       }
       /*
@@ -292,17 +295,16 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
        * file in question.
        */
       default: {
-        if (typeof value === "string") {
+        if (isString(value)) {
           if (!PROSE_KEYS.has(key) && looksLikeFileRef(value)) {
-            visitScalar(obj, key, "path", visit, false);
+            visitScalar(node, key, "path", visit, false);
           }
         } else if (Array.isArray(value)) {
-          const arr = value as unknown[];
-          for (let i = 0; i < arr.length; i += 1) {
-            const item = arr[i];
-            if (typeof item === "string") {
+          for (let i = 0; i < value.length; i += 1) {
+            const item = value[i];
+            if (isString(item)) {
               if (!PROSE_KEYS.has(key) && looksLikeFileRef(item)) {
-                visitIndexed(arr, i, "path", visit);
+                visitIndexed(value, i, "path", visit);
               }
             } else {
               walkDocRefs(item, visit);
@@ -317,7 +319,7 @@ export function walkDocRefs(node: unknown, visit: RefVisitor): void {
 }
 
 /** Rewrite every file-path reference in `doc` for a rename described by `ctx`. Mutates `doc`. */
-export function rewriteDocRefs(doc: unknown, ctx: RemapCtx): RewriteResult {
+export function rewriteDocRefs(doc: JsonValue, ctx: RemapCtx): RewriteResult {
   const changes: RefChange[] = [];
   walkDocRefs(doc, (value, refType, rootRelativeBare) => {
     const cls = classifyRef(value);
@@ -339,29 +341,28 @@ export function rewriteDocRefs(doc: unknown, ctx: RemapCtx): RewriteResult {
  * null, they are only counted — the read side of the same traversal.
  */
 function walkTags(
-  node: unknown,
+  node: JsonValue | undefined,
   oldTag: string,
   newTag: string | null,
   counter: { n: number },
 ): void {
   if (Array.isArray(node)) {
-    for (const item of node as unknown[]) {
+    for (const item of node) {
       walkTags(item, oldTag, newTag, counter);
     }
     return;
   }
-  if (!node || typeof node !== "object") {
+  if (!isJsonObject(node)) {
     return;
   }
-  const obj = node as Record<string, unknown>;
-  if (obj.tagName === oldTag) {
+  if (node.tagName === oldTag) {
     if (newTag !== null) {
-      obj.tagName = newTag;
+      node.tagName = newTag;
     }
     counter.n += 1;
   }
-  for (const key of Object.keys(obj)) {
-    walkTags(obj[key], oldTag, newTag, counter);
+  for (const key of Object.keys(node)) {
+    walkTags(node[key], oldTag, newTag, counter);
   }
 }
 
@@ -371,11 +372,7 @@ function walkTags(
  * `$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 } {
+export function rewriteTagName(doc: JsonValue, oldTag: string, newTag: string): TagRewriteResult {
   const counter = { n: 0 };
   if (oldTag !== newTag) {
     walkTags(doc, oldTag, newTag, counter);
@@ -389,7 +386,7 @@ export function rewriteTagName(
  * 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 {
+export function countTagUses(doc: JsonValue, tag: string): number {
   const counter = { n: 0 };
   walkTags(doc, tag, null, counter);
   return counter.n;