@alloy-js/core 0.23.0-dev.0 → 0.23.0-dev.8

package/src/devtools/devtools-transport.ts

@@ -0,0 +1,154 @@
+/**
+ * WebSocket transport for the Alloy devtools server.
+ *
+ * Handles HTTP serving of the devtools UI and WebSocket connection management.
+ * This module is concerned only with the transport layer — session lifecycle
+ * is managed by devtools-server.ts.
+ */
+import { readFileSync } from "node:fs";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+
+export interface DevtoolsTransportState {
+  port: number;
+  connected: boolean;
+  clients: Set<any>;
+  httpServer: ReturnType<typeof createHttpServer>;
+  ready: Promise<void>;
+  close(): Promise<void>;
+}
+
+let cachedAlloyVersion: string | null = null;
+
+/** Read the @alloy-js/core package version, cached after first call. */
+export function getAlloyVersion(): string {
+  if (cachedAlloyVersion) return cachedAlloyVersion;
+  try {
+    const pkgUrl = new URL("../../../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgUrl, "utf-8")) as {
+      version?: string;
+    };
+    cachedAlloyVersion = pkg.version ?? "0.0.0";
+  } catch {
+    cachedAlloyVersion = "0.0.0";
+  }
+  return cachedAlloyVersion;
+}
+
+/** Attempt to load the devtools UI HTML from known candidate paths. */
+function loadDevtoolsUiHtml(): string | null {
+  const candidates = [
+    new URL("../../dist/devtools/index.html", import.meta.url),
+    new URL("../../devtools/index.html", import.meta.url),
+    new URL("../../../devtools/dist/index.html", import.meta.url),
+  ];
+  for (const candidate of candidates) {
+    try {
+      return readFileSync(candidate, "utf-8");
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+export interface CreateTransportOptions {
+  port: number;
+  onConnection(socket: any): void;
+  onMessage(message: unknown): void;
+  onDisconnect(): void;
+}
+
+/**
+ * Create the HTTP + WebSocket transport. Returns when the server is listening.
+ * Only accepts one concurrent WebSocket connection.
+ */
+export async function createTransport(
+  options: CreateTransportOptions,
+): Promise<DevtoolsTransportState> {
+  const { WebSocketServer } = await import("ws");
+  const devtoolsUiHtml = loadDevtoolsUiHtml();
+
+  const httpServer = createHttpServer(
+    (req: IncomingMessage, res: ServerResponse) => {
+      const url = req.url ?? "/";
+      if (url !== "/" && url !== "/index.html") {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return;
+      }
+      if (!devtoolsUiHtml) {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(devtoolsUiHtml);
+    },
+  );
+  const wss = new WebSocketServer({ server: httpServer });
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("listening", resolve);
+    httpServer.once("error", reject);
+    httpServer.listen(options.port);
+  });
+
+  const address = httpServer.address();
+  const actualPort =
+    typeof address === "object" && address !== null ?
+      address.port
+    : options.port;
+
+  let resolveReady: (() => void) | undefined;
+  const ready = new Promise<void>((resolve) => {
+    resolveReady = resolve;
+  });
+
+  const clients = new Set<any>();
+  const state: DevtoolsTransportState = {
+    port: actualPort,
+    connected: false,
+    clients,
+    httpServer,
+    ready,
+    close: async () => {
+      await new Promise<void>((resolve) => wss.close(() => resolve()));
+      await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+      clients.clear();
+      state.connected = false;
+    },
+  };
+
+  wss.on("connection", (socket) => {
+    if (state.connected) {
+      socket.close(1000, "Another devtools client is already connected");
+      return;
+    }
+
+    clients.add(socket);
+    state.connected = true;
+    resolveReady?.();
+    options.onConnection(socket);
+
+    socket.on("message", (data) => {
+      try {
+        options.onMessage(JSON.parse(String(data)));
+      } catch {
+        // ignore malformed messages
+      }
+    });
+
+    socket.on("close", () => {
+      clients.delete(socket);
+      state.connected = clients.size > 0;
+      options.onDisconnect();
+    });
+  });
+
+  return state;
+}

package/src/devtools-entry.browser.ts

@@ -0,0 +1,52 @@
+export type {
+  BatchMessage,
+  ClientToServerMessage,
+  DebuggerInfoMessage,
+  DiagnosticInfo,
+  DiagnosticsReportMessage,
+  DirectoryAddedMessage,
+  DirectoryRemovedMessage,
+  EffectAddedMessage,
+  EffectEdgeInfo,
+  EffectEdgeUpdatedMessage,
+  EffectInfo,
+  EffectTrackMessage,
+  EffectTriggerMessage,
+  EffectUpdatedMessage,
+  FileAddedMessage,
+  FileRemovedMessage,
+  FileUpdatedMessage,
+  FlushJobsCompleteMessage,
+  RefAddedMessage,
+  RefInfo,
+  RenderCompleteMessage,
+  RenderErrorMessage,
+  RenderErrorStackEntry,
+  RenderNodeAddedMessage,
+  RenderNodeRemovedMessage,
+  RenderNodeUpdatedMessage,
+  RenderResetMessage,
+  RenderTreeNode,
+  RerenderBreakRequestMessage,
+  RerenderRequestMessage,
+  ScopeCreateMessage,
+  ScopeDeleteMessage,
+  ScopeInfo,
+  ScopeUpdateMessage,
+  ServerToClientMessage,
+  SourceLocation,
+  SymbolCreateMessage,
+  SymbolDeleteMessage,
+  SymbolInfo,
+  SymbolUpdateMessage,
+} from "./devtools/devtools-protocol.js";
+export {
+  enableDevtools,
+  enableDevtoolsAndConnect,
+  resetDevtoolsServerForTests,
+  waitForDevtoolsConnection,
+} from "./devtools/devtools-server.browser.js";
+export type {
+  DevtoolsServerInfo,
+  EnableDevtoolsOptions,
+} from "./devtools/devtools-server.browser.js";

package/src/devtools-entry.ts

@@ -0,0 +1,54 @@
+export type {
+  // Individual server→client message types
+  BatchMessage,
+  ClientToServerMessage,
+  DebuggerInfoMessage,
+  DiagnosticInfo,
+  DiagnosticsReportMessage,
+  DirectoryAddedMessage,
+  DirectoryRemovedMessage,
+  EffectAddedMessage,
+  EffectEdgeInfo,
+  EffectEdgeUpdatedMessage,
+  EffectInfo,
+  EffectTrackMessage,
+  EffectTriggerMessage,
+  EffectUpdatedMessage,
+  FileAddedMessage,
+  FileRemovedMessage,
+  FileUpdatedMessage,
+  FlushJobsCompleteMessage,
+  RefAddedMessage,
+  RefInfo,
+  RenderCompleteMessage,
+  RenderErrorMessage,
+  RenderErrorStackEntry,
+  RenderNodeAddedMessage,
+  RenderNodeRemovedMessage,
+  RenderNodeUpdatedMessage,
+  RenderResetMessage,
+  RenderTreeNode,
+  // Individual client→server message types
+  RerenderBreakRequestMessage,
+  RerenderRequestMessage,
+  ScopeCreateMessage,
+  ScopeDeleteMessage,
+  ScopeInfo,
+  ScopeUpdateMessage,
+  ServerToClientMessage,
+  SourceLocation,
+  SymbolCreateMessage,
+  SymbolDeleteMessage,
+  SymbolInfo,
+  SymbolUpdateMessage,
+} from "./devtools/devtools-protocol.js";
+export {
+  enableDevtools,
+  enableDevtoolsAndConnect,
+  resetDevtoolsServerForTests,
+  waitForDevtoolsConnection,
+} from "./devtools/devtools-server.js";
+export type {
+  DevtoolsServerInfo,
+  EnableDevtoolsOptions,
+} from "./devtools/devtools-server.js";

package/src/diagnostics.ts

@@ -0,0 +1,141 @@
+import { getRenderNodeId } from "./debug/index.js";
+import { broadcastDevtoolsMessage } from "./devtools/devtools-server.js";
+import { getContext } from "./reactivity.js";
+import { getRenderStackSnapshot } from "./render-stack.js";
+import type { SourceLocation } from "./runtime/component.js";
+
+export interface DiagnosticStackEntry {
+  name: string;
+  renderNodeId?: number;
+  source?: SourceLocation;
+}
+
+export type DiagnosticSeverity = "info" | "warning" | "error";
+
+export interface Diagnostic {
+  id: string;
+  message: string;
+  severity: DiagnosticSeverity;
+  source?: SourceLocation;
+  componentStack?: DiagnosticStackEntry[];
+}
+
+export interface DiagnosticInput {
+  message: string;
+  severity?: DiagnosticSeverity;
+  source?: SourceLocation;
+  componentStack?: DiagnosticStackEntry[];
+}
+
+export interface DiagnosticHandle {
+  dismiss(): void;
+}
+
+export class DiagnosticsCollector {
+  private entries = new Map<string, Diagnostic>();
+  private order: string[] = [];
+
+  emit(input: DiagnosticInput): DiagnosticHandle {
+    const componentStack =
+      input.componentStack ??
+      getRenderStackSnapshot().map((entry) => ({
+        name: entry.displayName,
+        renderNodeId:
+          entry.context?.meta?.renderNode ?
+            getRenderNodeId(entry.context.meta.renderNode)
+          : undefined,
+        source: entry.source,
+      }));
+    const source = input.source ?? componentStack.at(-1)?.source ?? undefined;
+    const id = `diag-${this.order.length + 1}-${Date.now()}`;
+    const diagnostic: Diagnostic = {
+      id,
+      message: input.message,
+      severity: input.severity ?? "warning",
+      source,
+      componentStack,
+    };
+    this.entries.set(id, diagnostic);
+    this.order.push(id);
+
+    // Broadcast updated diagnostics
+    this.broadcast();
+
+    return {
+      dismiss: () => {
+        this.entries.delete(id);
+        // Broadcast updated diagnostics after dismissal
+        this.broadcast();
+      },
+    };
+  }
+
+  getDiagnostics() {
+    return this.order
+      .map((id) => this.entries.get(id))
+      .filter((entry): entry is Diagnostic => Boolean(entry));
+  }
+
+  private broadcast() {
+    broadcastDevtoolsMessage({
+      type: "diagnostics:report",
+      diagnostics: this.getDiagnostics(),
+    });
+  }
+}
+
+const DIAGNOSTICS_META_KEY = "diagnostics";
+
+export function attachDiagnosticsCollector(collector: DiagnosticsCollector) {
+  const context = getContext();
+  if (!context) return;
+  context.meta ??= {};
+  context.meta[DIAGNOSTICS_META_KEY] = collector;
+}
+
+function getDiagnosticsCollectorFromContext():
+  | DiagnosticsCollector
+  | undefined {
+  let context = getContext();
+  while (context) {
+    const collector = context.meta?.[DIAGNOSTICS_META_KEY] as
+      | DiagnosticsCollector
+      | undefined;
+    if (collector) return collector;
+    context = context.owner;
+  }
+  return undefined;
+}
+
+export function emitDiagnostic(input: DiagnosticInput): DiagnosticHandle {
+  const collector = getDiagnosticsCollectorFromContext();
+  if (!collector) {
+    return {
+      dismiss: () => undefined,
+    };
+  }
+  return collector.emit(input);
+}
+
+export function reportDiagnostics(collector: DiagnosticsCollector) {
+  const diagnostics = collector.getDiagnostics();
+  if (diagnostics.length === 0) return;
+
+  for (const diagnostic of diagnostics) {
+    const location =
+      diagnostic.source ?
+        ` (${diagnostic.source.fileName}:${diagnostic.source.lineNumber}:${diagnostic.source.columnNumber})`
+      : "";
+    const line = `${diagnostic.message}${location}`;
+    if (diagnostic.severity === "error") {
+      // eslint-disable-next-line no-console
+      console.error(line);
+    } else if (diagnostic.severity === "warning") {
+      // eslint-disable-next-line no-console
+      console.warn(line);
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(line);
+    }
+  }
+}

package/src/index.ts

@@ -1,17 +1,12 @@
 export {
   TrackOpTypes,
   TriggerOpTypes,
-  computed,
   isProxy,
   isReactive,
   isRef,
   reactive,
-  ref,
   shallowReactive,
-  shallowRef,
   toRaw,
-  toRef,
-  toRefs,
   track,
   trigger,
   watch,
@@ -28,6 +23,7 @@ export * from "./components/index.js";
 export * from "./content-slot.js";
 export * from "./context.js";
 export * from "./context/index.js";
+export * from "./diagnostics.js";
 export * from "./library-symbol-reference.js";
 export * from "./name-policy.js";
 export * from "./props-combinators.js";
@@ -45,4 +41,4 @@ export * from "./symbols/symbol-flow.js";
 export * from "./tap.js";
 export * from "./utils.js";
 export * from "./write-output.js";
-import "./debug.js";
+import "./debug/index.js";

package/src/print-hook.ts

@@ -0,0 +1,22 @@
+/**
+ * Print hook types and utilities.
+ * This is a separate file to avoid circular dependencies between render.ts and debug/render.ts.
+ */
+
+export const printHookTag = Symbol();
+
+export interface PrintHook {
+  [printHookTag]: true;
+  transform?(tree: RenderedTextTree): RenderedTextTree;
+  print?(
+    tree: RenderedTextTree,
+    print: (subtree: RenderedTextTree) => import("prettier").Doc,
+  ): import("prettier").Doc;
+  subtree: RenderedTextTree;
+}
+
+export function isPrintHook(type: unknown): type is PrintHook {
+  return typeof type === "object" && type !== null && printHookTag in type;
+}
+
+export type RenderedTextTree = (string | RenderedTextTree | PrintHook)[];

package/src/reactive-union-set.ts

@@ -130,27 +130,36 @@ export class ReactiveUnionSet<T> extends Set<T> {
      */
     const prevValues = new Map<T, T>();
 
-    effect(() => {
-      for (const [prevSourceValue, prevTargetValue] of prevValues) {
-        if (!subset.has(prevSourceValue)) {
-          untrack(() => onDelete?.(prevSourceValue));
-          prevValues.delete(prevSourceValue);
-          this.delete(prevTargetValue);
+    effect(
+      () => {
+        for (const [prevSourceValue, prevTargetValue] of prevValues) {
+          if (!subset.has(prevSourceValue)) {
+            untrack(() => onDelete?.(prevSourceValue));
+            prevValues.delete(prevSourceValue);
+            this.delete(prevTargetValue);
+          }
         }
-      }
 
-      for (const value of subset) {
-        if (!prevValues.has(value)) {
-          if (onAdd) {
-            const added = untrack(() => onAdd(value));
-            prevValues.set(value, added);
-          } else {
-            this.add(value);
-            prevValues.set(value, value);
+        for (const value of subset) {
+          if (!prevValues.has(value)) {
+            if (onAdd) {
+              const added = untrack(() => onAdd(value));
+              prevValues.set(value, added);
+            } else {
+              this.add(value);
+              prevValues.set(value, value);
+            }
           }
         }
-      }
-    });
+      },
+      undefined,
+      {
+        debug: {
+          name: "reactiveUnionSet:subsetSync",
+          type: "collection",
+        },
+      },
+    );
   }
 
   createDerivedSet<U>(mapper: (value: T) => U | U[]) {
@@ -184,18 +193,27 @@ export class ReactiveUnionSet<T> extends Set<T> {
 
     this._indexes.push({
       add: (value: T) => {
-        effect((prev: U[] | U | undefined) => {
-          for (const id of [prev].flat()) {
-            unref(id as any);
-          }
+        effect(
+          (prev: U[] | U | undefined) => {
+            for (const id of [prev].flat()) {
+              unref(id as any);
+            }
 
-          const mappedValue = mapper(value);
-          for (const id of [mappedValue].flat()) {
-            ref(id as any);
-          }
+            const mappedValue = mapper(value);
+            for (const id of [mappedValue].flat()) {
+              ref(id as any);
+            }
 
-          return mappedValue;
-        });
+            return mappedValue;
+          },
+          undefined,
+          {
+            debug: {
+              name: `reactiveUnionSet:derived:${mapper.name || "mapper"}`,
+              type: "collection",
+            },
+          },
+        );
       },
       delete: (value: T) => {
         const mappedValue = mapper(value);
@@ -212,24 +230,36 @@ export class ReactiveUnionSet<T> extends Set<T> {
     const index = shallowReactive(new Map<U, T>());
     this._indexes.push({
       add: (value: T) => {
-        effect((oldValue) => {
-          if (oldValue) {
-            for (const id of [oldValue].flat()) {
-              index.delete(id as U);
+        type MappedValue = U extends readonly (infer InnerArr)[] ? InnerArr : U;
+        effect<MappedValue[]>(
+          (oldValue) => {
+            if (oldValue) {
+              for (const id of [oldValue].flat()) {
+                index.delete(id as U);
+              }
             }
-          }
 
-          // we filter to avoid overwriting existing values (first wins)
-          const mappedValues = [mapper(value)]
-            .flat()
-            .filter((v) => untrack(() => !index.has(v as U)));
+            // we filter to avoid overwriting existing values (first wins)
+            const mappedValues = [mapper(value)]
+              .flat()
+              .filter((v) =>
+                untrack(() => !index.has(v as U)),
+              ) as MappedValue[];
 
-          for (const id of mappedValues) {
-            index.set(id as U, value as any);
-          }
+            for (const id of mappedValues) {
+              index.set(id as U, value as any);
+            }
 
-          return mappedValues;
-        });
+            return mappedValues;
+          },
+          undefined as MappedValue[] | undefined,
+          {
+            debug: {
+              name: `reactiveUnionSet:index:${mapper.name || "mapper"}`,
+              type: "collection",
+            },
+          },
+        );
       },
       delete: (value: T) => {
         const mappedValue = mapper(value);