@alloy-js/core 0.23.0-dev.1 → 0.23.0-dev.10

package/src/debug/files.test.tsx

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, expect, it } from "vitest";
+import WebSocket from "ws";
+import {
+  createMessageCollector,
+  type DevtoolsMessage,
+} from "../../testing/devtools-utils.js";
+import { Output } from "../components/Output.jsx";
+import { Show } from "../components/Show.jsx";
+import { SourceDirectory } from "../components/SourceDirectory.jsx";
+import { SourceFile } from "../components/SourceFile.jsx";
+import {
+  enableDevtools,
+  resetDevtoolsServerForTests,
+} from "../devtools/devtools-server.js";
+import { ref } from "../reactivity.js";
+import { renderAsync } from "../render.js";
+import { flushJobsAsync } from "../scheduler.js";
+
+let socket: WebSocket | undefined;
+
+beforeEach(async () => {
+  const server = await enableDevtools({ port: 0 });
+  socket = new WebSocket(`ws://127.0.0.1:${server.port}`);
+
+  await new Promise<void>((resolve, reject) => {
+    socket?.once("open", resolve);
+    socket?.once("error", reject);
+  });
+});
+
+afterEach(async () => {
+  if (socket) {
+    socket.close();
+    socket = undefined;
+  }
+
+  await resetDevtoolsServerForTests();
+});
+
+it("emits file and directory add/update/remove messages", async () => {
+  const show = ref(true);
+  const collector = createMessageCollector(socket!);
+
+  await renderAsync(
+    <Output>
+      <Show when={show.value}>
+        <SourceDirectory path="src">
+          <SourceFile path="index.ts" filetype="ts">
+            {"export const value = 1;"}
+          </SourceFile>
+        </SourceDirectory>
+      </Show>
+    </Output>,
+  );
+
+  const initialMessages = await collector.waitForRender();
+  const initialFiles = initialMessages.filter((m: DevtoolsMessage) =>
+    m.type.startsWith("files:"),
+  );
+  expect(initialFiles[0]).toMatchObject({
+    path: "./",
+  });
+  expect(initialFiles[1]).toMatchObject({
+    type: "files:directoryAdded",
+    path: "src",
+  });
+  expect(initialFiles[2]).toMatchObject({
+    type: "files:fileAdded",
+    path: "src/index.ts",
+    filetype: "ts",
+  });
+  expect(initialFiles[3]).toMatchObject({
+    type: "files:fileUpdated",
+    path: "src/index.ts",
+    filetype: "ts",
+    contents: expect.any(String),
+  });
+
+  show.value = false;
+  await flushJobsAsync();
+
+  const updateMessages = await collector.waitForFlush();
+  const updateFiles = updateMessages.filter((m: DevtoolsMessage) =>
+    m.type.startsWith("files:"),
+  );
+  collector.stop();
+
+  expect(updateFiles[0]).toMatchObject({
+    type: "files:fileRemoved",
+    path: "src/index.ts",
+  });
+  expect(updateFiles[1]).toMatchObject({
+    type: "files:directoryRemoved",
+    path: "src",
+  });
+});

package/src/debug/files.ts

@@ -0,0 +1,40 @@
+import { emitDevtoolsMessage, isDevtoolsEnabled } from "./trace.js";
+
+export interface FileUpdateInfo {
+  path: string;
+  filetype: string;
+  contents: string;
+}
+
+const fileContentCache = new Map<string, string>();
+
+/** Record a directory being added to the output. */
+export function recordDirectory(path: string) {
+  if (!isDevtoolsEnabled()) return;
+  emitDevtoolsMessage({ type: "files:directoryAdded", path });
+}
+
+/** Record a file being added to the output. */
+export function recordFile(path: string, filetype: string) {
+  if (!isDevtoolsEnabled()) return;
+  emitDevtoolsMessage({ type: "files:fileAdded", path, filetype });
+}
+
+/** Notify devtools that a file's contents have changed. De-duplicates by content. */
+export function updated(info: FileUpdateInfo) {
+  const previous = fileContentCache.get(info.path);
+  if (previous === info.contents) return;
+  fileContentCache.set(info.path, info.contents);
+
+  emitDevtoolsMessage({
+    type: "files:fileUpdated",
+    path: info.path,
+    filetype: info.filetype,
+    contents: info.contents,
+  });
+}
+
+/** Clear all cached file state. Called when a new render begins. */
+export function reset() {
+  fileContentCache.clear();
+}

package/src/debug/index.ts

@@ -0,0 +1,128 @@
+import {
+  assertDevtoolsConnectedForSyncRender,
+  initDevtoolsIfEnabled,
+  isDevtoolsEnabled,
+} from "../devtools/devtools-server.js";
+import {
+  debugContext,
+  debugRender,
+  debugStack,
+  debugTree,
+  debugWatch,
+} from "./cli.js";
+import {
+  ensureRef,
+  register,
+  registerRef,
+  reset,
+  track,
+  trigger,
+  update,
+} from "./effects.js";
+import {
+  recordDirectory,
+  recordFile,
+  reset as resetFiles,
+  updated,
+} from "./files.js";
+import {
+  appendCustomContext,
+  appendFragmentChild,
+  appendPrintHook,
+  appendTextNode,
+  beginComponent,
+  complete,
+  error,
+  flushJobsComplete,
+  initialize,
+  prepareMemoNode,
+} from "./render.js";
+import {
+  registerScope,
+  registerSymbol,
+  relocateScope,
+  reset as resetSymbols,
+  unregisterScope,
+  unregisterSymbol,
+} from "./symbols.js";
+import { trace, type TracePhaseInfo } from "./trace.js";
+
+export { captureSourceLocation } from "./effects.js";
+export type {
+  EffectDebugInfo,
+  EffectEdgeDebugInfo,
+  RefDebugInfo,
+} from "./effects.js";
+export { getRenderNodeId, type RenderTreeNodeInfo } from "./render.js";
+export type {
+  BeginComponentOptions,
+  ComponentDebugSession,
+  RenderErrorInfo,
+  RenderErrorStackEntry,
+} from "./render.js";
+export {
+  isConsoleTraceEnabled,
+  isDevtoolsEnabled,
+  trace,
+  TracePhase,
+  type TracePhaseInfo,
+} from "./trace.js";
+
+/** The full debug runtime interface, derived from the `debug` object implementation. */
+export type DebugRuntime = typeof debug;
+
+export const debug = {
+  component: {
+    stack: debugStack,
+    tree: debugTree,
+    watch: debugWatch,
+    render: debugRender,
+    context: debugContext,
+  },
+  effect: {
+    register,
+    update,
+    registerRef,
+    ensureRef,
+    track,
+    trigger,
+    reset,
+  },
+  render: {
+    initialize,
+    appendTextNode,
+    appendCustomContext,
+    appendPrintHook,
+    appendFragmentChild,
+    beginComponent,
+    prepareMemoNode,
+    error,
+    complete,
+    flushJobsComplete,
+  },
+  files: {
+    recordDirectory,
+    recordFile,
+    updated,
+    reset: resetFiles,
+  },
+  symbols: {
+    registerScope,
+    relocateScope,
+    unregisterScope,
+    registerSymbol,
+    unregisterSymbol,
+    reset: resetSymbols,
+  },
+  trace(phase: TracePhaseInfo, cb: () => string, triggerIds?: Set<number>) {
+    trace(phase, cb, triggerIds ?? new Set());
+  },
+  async prepare(): Promise<void> {
+    await initDevtoolsIfEnabled();
+  },
+  assertReadyForSyncRender(): void {
+    if (isDevtoolsEnabled()) {
+      assertDevtoolsConnectedForSyncRender();
+    }
+  },
+};

package/src/debug/render.test.tsx

@@ -0,0 +1,379 @@
+import { afterEach, beforeEach, expect, it } from "vitest";
+import WebSocket from "ws";
+import {
+  createMessageCollector,
+  filterRenderTreeMessages,
+  type DevtoolsMessage,
+} from "../../testing/devtools-utils.js";
+import { For } from "../components/For.jsx";
+import { Output } from "../components/Output.jsx";
+import { Show } from "../components/Show.jsx";
+import {
+  enableDevtools,
+  resetDevtoolsServerForTests,
+} from "../devtools/devtools-server.js";
+import { ref } from "../reactivity.js";
+import { renderAsync } from "../render.js";
+import { flushJobsAsync } from "../scheduler.js";
+
+let socket: WebSocket | undefined;
+
+beforeEach(async () => {
+  const server = await enableDevtools({ port: 0 });
+  socket = new WebSocket(`ws://127.0.0.1:${server.port}`);
+
+  await new Promise<void>((resolve, reject) => {
+    socket?.once("open", resolve);
+    socket?.once("error", reject);
+  });
+});
+
+afterEach(async () => {
+  if (socket) {
+    socket.close();
+    socket = undefined;
+  }
+
+  await resetDevtoolsServerForTests();
+});
+
+it("emits render:complete on successful render", async () => {
+  const collector = createMessageCollector(socket!);
+
+  await renderAsync(<Output />);
+
+  const messages = await collector.waitForRender();
+
+  expect(messages.at(-1)).toMatchObject({ type: "render:complete" });
+  collector.stop();
+});
+
+it("emits render:error on render failure", async () => {
+  function Boom() {
+    throw new Error("Boom");
+  }
+
+  const collector = createMessageCollector(socket!);
+
+  await expect(
+    renderAsync(
+      <Output>
+        <Boom />
+      </Output>,
+    ),
+  ).rejects.toThrow("Boom");
+
+  const messages = await collector.waitForRender();
+  const renderMessages = messages.filter((m: DevtoolsMessage) =>
+    m.type.startsWith("render:"),
+  );
+  expect(renderMessages.at(-1)).toMatchObject({
+    type: "render:error",
+    name: expect.any(String),
+    message: expect.any(String),
+    componentStack: expect.any(Array),
+  });
+  collector.stop();
+});
+
+it("sends render tree messages during render", async () => {
+  function Foo() {
+    return (
+      <>
+        Hello
+        <br />
+        {() => "World"}
+      </>
+    );
+  }
+
+  const collector = createMessageCollector(socket!);
+
+  await renderAsync(
+    <Output>
+      <Foo />
+    </Output>,
+  );
+
+  const messages = await collector.waitForRender();
+  const renderMessages = filterRenderTreeMessages(messages);
+  collector.stop();
+
+  expect(renderMessages[0]).toMatchObject({ type: "render:reset" });
+  expect(renderMessages[1]).toMatchObject({
+    type: "render:nodeAdded",
+    parentId: null,
+    node: {},
+  });
+  expect(renderMessages[2]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {
+      name: "Output",
+    },
+  });
+  expect(renderMessages[3]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {
+      name: "Context Binder",
+    },
+  });
+  expect(renderMessages[4]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {},
+  });
+  expect(renderMessages[5]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {
+      name: "Context FormatOptions.*",
+    },
+  });
+  expect(renderMessages[6]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {},
+  });
+  expect(renderMessages[7]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {
+      name: "SourceDirectory",
+    },
+  });
+  expect(renderMessages[8]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {
+      name: "Context SourceDirectory",
+    },
+  });
+  expect(renderMessages[9]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {},
+  });
+  expect(renderMessages[10]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {
+      name: "Foo",
+    },
+  });
+  expect(renderMessages[11]).toMatchObject({
+    type: "render:nodeAdded",
+    node: { value: "Hello" },
+  });
+  expect(renderMessages[12]).toMatchObject({
+    type: "render:nodeAdded",
+    node: { name: "br" },
+  });
+  expect(renderMessages[13]).toMatchObject({
+    type: "render:nodeAdded",
+    node: {},
+  });
+  expect(renderMessages[14]).toMatchObject({
+    type: "render:nodeAdded",
+    node: { value: "World" },
+  });
+});
+
+it("rerenders when devtools requests rerender", async () => {
+  let renderCount = 0;
+
+  function Display() {
+    renderCount += 1;
+    return "Hi";
+  }
+
+  const collector = createMessageCollector(socket!);
+
+  await renderAsync(
+    <Output>
+      <Display />
+    </Output>,
+  );
+
+  const messages = await collector.waitForRender();
+  const renderMessages = filterRenderTreeMessages(messages);
+  const displayNode = renderMessages.find(
+    (message: DevtoolsMessage) =>
+      message.type === "render:nodeAdded" &&
+      (message as { node?: { name?: string } }).node?.name === "Display",
+  ) as { node?: { id?: number } } | undefined;
+
+  expect(renderCount).toBe(1);
+  expect(displayNode?.node?.id).toEqual(expect.any(Number));
+
+  socket!.send(
+    JSON.stringify({ type: "render:rerender", id: displayNode!.node!.id }),
+  );
+
+  await collector.waitForFlush();
+
+  expect(renderCount).toBe(2);
+  collector.stop();
+});
+
+it("sends render tree messages during render with For component", async () => {
+  const collector = createMessageCollector(socket!);
+  function Display(props: any) {
+    return <>item {props.item}</>;
+  }
+  await renderAsync(
+    <Output>
+      <For each={["a", "b"]}>{(item) => <Display item={item} />}</For>
+    </Output>,
+  );
+
+  const messages = await collector.waitForRender();
+  const renderMessages = filterRenderTreeMessages(messages);
+  collector.stop();
+
+  expect(renderMessages[0]).toMatchObject({ type: "render:reset" });
+  expect(renderMessages).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        type: "render:nodeAdded",
+        node: expect.objectContaining({ name: "For" }),
+      }),
+      expect.objectContaining({
+        type: "render:nodeAdded",
+        node: expect.objectContaining({ value: "a" }),
+      }),
+      expect.objectContaining({
+        type: "render:nodeAdded",
+        node: expect.objectContaining({ value: "b" }),
+      }),
+    ]),
+  );
+});
+
+it("emits nodeUpdated when component props change", async () => {
+  const count = ref(1);
+  const collector = createMessageCollector(socket!);
+
+  function Counter(props: { value: number }) {
+    return `Count: ${props.value}`;
+  }
+
+  await renderAsync(
+    <Output>
+      <Counter value={count.value} />
+    </Output>,
+  );
+
+  await collector.waitForRender();
+
+  count.value += 1;
+  await flushJobsAsync();
+
+  const updateMessages = await collector.waitForFlush();
+  const updateRenderMessages = filterRenderTreeMessages(updateMessages);
+
+  const nodeUpdated = updateRenderMessages.filter(
+    (m: DevtoolsMessage) => m.type === "render:nodeUpdated",
+  );
+
+  expect(nodeUpdated[0]).toMatchObject({
+    type: "render:nodeUpdated",
+    id: expect.any(Number),
+  });
+  collector.stop();
+});
+
+it("emits nodeRemoved when conditional content disappears", async () => {
+  const show = ref(true);
+  const collector = createMessageCollector(socket!);
+
+  function Maybe() {
+    return <Show when={show.value}>hi</Show>;
+  }
+
+  await renderAsync(
+    <Output>
+      <Maybe />
+    </Output>,
+  );
+
+  await collector.waitForRender();
+
+  show.value = false;
+  await flushJobsAsync();
+
+  const updateMessages = await collector.waitForFlush();
+  const updateRenderMessages = filterRenderTreeMessages(updateMessages);
+
+  const removed = updateRenderMessages.filter(
+    (m: DevtoolsMessage) => m.type === "render:nodeRemoved",
+  );
+
+  expect(removed[0]).toMatchObject({
+    type: "render:nodeRemoved",
+    parentId: expect.any(Number),
+    id: expect.any(Number),
+  });
+  collector.stop();
+});
+
+it("emits proper events when items are added/removed in For component", async () => {
+  const items = ref(["a", "b"]);
+  const collector = createMessageCollector(socket!);
+
+  function Display(props: any) {
+    return <>item {props.item}</>;
+  }
+  await renderAsync(
+    <Output>
+      <For each={items}>{(item) => <Display item={item} />}</For>
+    </Output>,
+  );
+
+  const originalMessages = await collector.waitForRender();
+
+  // Track all nodes that are currently in the tree
+  const activeNodes = new Map<
+    number,
+    { parentId: number | null; kind: string; name?: string }
+  >();
+
+  function processMessages(messages: any[]) {
+    for (const msg of messages) {
+      if (msg.type === "render:nodeAdded") {
+        const nodeId = msg.node.id;
+        const parentId = msg.parentId;
+
+        // Root node has null parent, otherwise parent must exist
+        if (parentId !== null && !activeNodes.has(parentId)) {
+          throw new Error(
+            `Node ${nodeId} (${msg.node.kind}${msg.node.name ? `: ${msg.node.name}` : ""}) ` +
+              `added with parent ${parentId} but parent is not in active nodes. ` +
+              `Active nodes: ${[...activeNodes.keys()].join(", ")}`,
+          );
+        }
+
+        activeNodes.set(nodeId, {
+          parentId,
+          kind: msg.node.kind,
+          name: msg.node.name,
+        });
+      } else if (msg.type === "render:nodeRemoved") {
+        const nodeId = msg.id;
+        if (!activeNodes.has(nodeId)) {
+          throw new Error(
+            `Node ${nodeId} removed but was not in active nodes. ` +
+              `Active nodes: ${[...activeNodes.keys()].join(", ")}`,
+          );
+        }
+        activeNodes.delete(nodeId);
+      }
+    }
+  }
+
+  // Process initial render
+  processMessages(filterRenderTreeMessages(originalMessages));
+
+  // Mutate the list
+  items.value.push("c");
+  items.value.unshift("0");
+  await flushJobsAsync();
+
+  const updateMessages = await collector.waitForFlush();
+  const updateRenderMessages = filterRenderTreeMessages(updateMessages);
+
+  // Process update - this will throw if parent invariant is violated
+  processMessages(updateRenderMessages);
+});