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

package/src/debug/symbols.test.tsx

@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, expect, it } from "vitest";
+import WebSocket from "ws";
+import { createMessageCollector } from "../../testing/devtools-utils.js";
+import { createOutputBinder, createScope, createSymbol } from "../binder.js";
+import {
+  enableDevtools,
+  resetDevtoolsServerForTests,
+} from "../devtools/devtools-server.js";
+import { effect } from "../reactivity.js";
+import { flushJobsAsync } from "../scheduler.js";
+import { BasicScope } from "../symbols/basic-scope.js";
+import { BasicSymbol } from "../symbols/basic-symbol.js";
+import { debug } from "./index.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 tracking info", async () => {
+  const collector = createMessageCollector(socket!);
+  const binder = createOutputBinder();
+
+  const scope = createScope(BasicScope, "root", undefined, { binder });
+  const symbol = createSymbol(BasicSymbol, "Foo", scope.symbols, { binder });
+  effect(() => {
+    void symbol.name;
+  });
+  symbol.name = "hi";
+  await flushJobsAsync();
+  const items = (await collector.waitForFlush()).filter((m) =>
+    m.type.startsWith("effect:track"),
+  );
+  expect(items.length).toBeGreaterThan(0);
+});
+
+it("emits symbol and scope add/update/remove messages", async () => {
+  const collector = createMessageCollector(socket!);
+  const binder = createOutputBinder();
+
+  const scope = createScope(BasicScope, "root", undefined, { binder });
+  const symbol = createSymbol(BasicSymbol, "Foo", scope.symbols, { binder });
+
+  effect(() => {
+    void scope.name;
+  });
+  scope.name = "root-updated";
+  symbol.name = "FooUpdated";
+
+  debug.symbols.unregisterSymbol(symbol);
+  debug.symbols.unregisterScope(scope);
+
+  await flushJobsAsync();
+
+  const messages = await collector.waitForFlush();
+  const symbolsMessages = messages.filter((m) => {
+    return m.type.startsWith("scope:") || m.type.startsWith("symbol:");
+  });
+  collector.stop();
+
+  expect(symbolsMessages[0]).toMatchObject({
+    type: "scope:create",
+    scope: expect.objectContaining({ name: "root" }),
+  });
+
+  expect(symbolsMessages[1]).toMatchObject({
+    type: "symbol:addToScope",
+  });
+
+  expect(symbolsMessages[2]).toMatchObject({
+    type: "symbol:create",
+    symbol: expect.objectContaining({ name: "Foo" }),
+  });
+  expect(symbolsMessages[3]).toMatchObject({
+    type: "scope:update",
+    scope: expect.objectContaining({ name: "root-updated" }),
+  });
+  expect(symbolsMessages[4]).toMatchObject({
+    type: "symbol:update",
+    symbol: expect.objectContaining({ name: "FooUpdated" }),
+  });
+  expect(symbolsMessages[5]).toMatchObject({
+    type: "symbol:delete",
+    id: expect.any(Number),
+  });
+  expect(symbolsMessages[6]).toMatchObject({
+    type: "scope:delete",
+    id: expect.any(Number),
+  });
+});

package/src/debug/symbols.ts

@@ -0,0 +1,230 @@
+import { watch } from "@vue/reactivity";
+import { getContext, untrack } from "../reactivity.js";
+import type { OutputScope } from "../symbols/output-scope.js";
+import type { OutputSymbol } from "../symbols/output-symbol.js";
+import { getRenderNodeId } from "./render.js";
+import { sanitizeRecord } from "./serialize.js";
+import {
+  emitDevtoolsMessage,
+  isDevtoolsEnabled,
+  TracePhase,
+  traceType,
+} from "./trace.js";
+
+interface ScopeSnapshot {
+  id: number;
+  name: string;
+  parentId: number | null;
+  ownerSymbolId: number | null;
+  isMemberScope: boolean;
+  renderNodeId: number | null;
+  metadata: Record<string, unknown> | undefined;
+  debugInfo: Record<string, unknown> | undefined;
+  children: Array<{ id: number; name: string }>;
+  spaces: Array<{ key: string; symbols: Array<{ id: number; name: string }> }>;
+}
+
+interface SymbolSnapshot {
+  id: number;
+  name: string;
+  originalName: string;
+  scopeId: number | null;
+  ownerSymbolId: number | null;
+  isMemberSymbol: boolean;
+  isTransient: boolean;
+  isAlias: boolean;
+  movedToId: number | null;
+  renderNodeId: number | null;
+  metadata: Record<string, unknown> | undefined;
+  debugInfo: Record<string, unknown> | undefined;
+  memberSpaces: Array<{
+    key: string;
+    symbols: Array<{ id: number; name: string }>;
+  }>;
+}
+
+const scopeWatchers = new Map<number, () => void>();
+const symbolWatchers = new Map<number, () => void>();
+
+function shallowEqual<T extends object>(a: T, b: T) {
+  const aRecord = a as Record<string, unknown>;
+  const bRecord = b as Record<string, unknown>;
+  const aKeys = Object.keys(aRecord);
+  const bKeys = Object.keys(bRecord);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    const aValue = aRecord[key];
+    const bValue = bRecord[key];
+    if (aValue === bValue) continue;
+    if (aValue === undefined || bValue === undefined) return false;
+    const aType = typeof aValue;
+    const bType = typeof bValue;
+    if (aType === "object" || bType === "object") {
+      if (JSON.stringify(aValue) !== JSON.stringify(bValue)) return false;
+    } else if (aValue !== bValue) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function sanitizeDebugInfo(input: Record<string, unknown> | undefined) {
+  return sanitizeRecord(input);
+}
+
+function getRenderNodeIdForCurrentContext() {
+  return untrack(() => {
+    const context = getContext();
+    let current = context;
+    while (current) {
+      const renderNode = current.meta?.renderNode as
+        | Parameters<typeof getRenderNodeId>[0]
+        | undefined;
+      if (renderNode) {
+        return getRenderNodeId(renderNode) ?? null;
+      }
+      current = current.owner;
+    }
+    return null;
+  });
+}
+
+function snapshotScope(
+  scope: OutputScope,
+  renderNodeId: number | null,
+): ScopeSnapshot {
+  return {
+    id: scope.id,
+    name: scope.name,
+    parentId: scope.parent?.id ?? null,
+    ownerSymbolId: scope.ownerSymbol?.id ?? null,
+    isMemberScope: scope.isMemberScope,
+    renderNodeId,
+    metadata: sanitizeRecord(scope.metadata),
+    debugInfo: sanitizeDebugInfo(scope.debugInfo),
+    children: untrack(() =>
+      Array.from(scope.children).map((child) => ({
+        id: child.id,
+        name: child.name,
+      })),
+    ),
+    spaces: untrack(() =>
+      scope.spaces.map((space) => ({
+        key: space.key,
+        symbols: Array.from(space).map((symbol) => ({
+          id: symbol.id,
+          name: symbol.name,
+        })),
+      })),
+    ),
+  };
+}
+
+function snapshotSymbol(
+  symbol: OutputSymbol,
+  renderNodeId: number | null,
+): SymbolSnapshot {
+  return {
+    id: symbol.id,
+    name: symbol.name,
+    originalName: symbol.originalName,
+    scopeId: symbol.scope?.id ?? null,
+    ownerSymbolId: symbol.ownerSymbol?.id ?? null,
+    isMemberSymbol: symbol.isMemberSymbol,
+    isTransient: symbol.isTransient,
+    isAlias: symbol.isAlias,
+    movedToId: symbol.movedTo?.id ?? null,
+    renderNodeId,
+    metadata: sanitizeRecord(symbol.metadata),
+    debugInfo: sanitizeDebugInfo(symbol.debugInfo),
+    memberSpaces: symbol.memberSpaces.map((space) => ({
+      key: space.key,
+      symbols: Array.from(space).map((member) => ({
+        id: member.id,
+        name: member.name,
+      })),
+    })),
+  };
+}
+
+export function registerScope(scope: OutputScope) {
+  if (!isDevtoolsEnabled()) return;
+  if (scopeWatchers.has(scope.id)) return;
+  untrack(() => {
+    const renderNodeId = getRenderNodeIdForCurrentContext();
+    let previous = snapshotScope(scope, renderNodeId);
+    emitDevtoolsMessage({
+      type: traceType(TracePhase.scope.create),
+      scope: previous,
+    });
+    const stop = watch(
+      () => snapshotScope(scope, renderNodeId),
+      (next) => {
+        if (!shallowEqual(previous, next)) {
+          previous = next;
+          emitDevtoolsMessage({
+            type: traceType(TracePhase.scope.update),
+            scope: next,
+          });
+        }
+      },
+    );
+    scopeWatchers.set(scope.id, stop);
+  });
+}
+
+export function unregisterScope(scope: OutputScope) {
+  if (!isDevtoolsEnabled()) return;
+  const stop = scopeWatchers.get(scope.id);
+  if (stop) stop();
+  scopeWatchers.delete(scope.id);
+  emitDevtoolsMessage({
+    type: traceType(TracePhase.scope.delete),
+    id: scope.id,
+  });
+}
+
+export function registerSymbol(symbol: OutputSymbol) {
+  if (!isDevtoolsEnabled()) return;
+  if (symbolWatchers.has(symbol.id)) return;
+  untrack(() => {
+    const renderNodeId = getRenderNodeIdForCurrentContext();
+    let previous = snapshotSymbol(symbol, renderNodeId);
+    emitDevtoolsMessage({
+      type: traceType(TracePhase.symbol.create),
+      symbol: previous,
+    });
+    const stop = watch(
+      () => snapshotSymbol(symbol, renderNodeId),
+      (next) => {
+        if (!shallowEqual(previous, next)) {
+          previous = next;
+          emitDevtoolsMessage({
+            type: traceType(TracePhase.symbol.update),
+            symbol: next,
+          });
+        }
+      },
+    );
+    symbolWatchers.set(symbol.id, stop);
+  });
+}
+
+export function unregisterSymbol(symbol: OutputSymbol) {
+  if (!isDevtoolsEnabled()) return;
+  const stop = symbolWatchers.get(symbol.id);
+  if (stop) stop();
+  symbolWatchers.delete(symbol.id);
+  emitDevtoolsMessage({
+    type: traceType(TracePhase.symbol.delete),
+    id: symbol.id,
+  });
+}
+
+/** Stop all watchers and clear tracked state. Called when a new render begins. */
+export function reset() {
+  for (const stop of scopeWatchers.values()) stop();
+  for (const stop of symbolWatchers.values()) stop();
+  scopeWatchers.clear();
+  symbolWatchers.clear();
+}

package/src/debug/trace.ts

@@ -0,0 +1,312 @@
+/**
+ * Trace helpers and configuration.
+ */
+import type { ServerToClientMessage } from "../devtools/devtools-protocol.js";
+import {
+  broadcastDevtoolsMessage,
+  isDevtoolsEnabled,
+  type DevtoolsMessage,
+} from "../devtools/devtools-server.js";
+import { untrack } from "../reactivity.js";
+
+export { isDevtoolsEnabled } from "../devtools/devtools-server.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Environment configuration
+// ─────────────────────────────────────────────────────────────────────────────
+
+const traceEnv = process.env.ALLOY_TRACE ?? "";
+const tracePhases = new Set<string>(
+  traceEnv === "" ? [] : traceEnv.split(",").map((t) => t.trim()),
+);
+
+const debuggerIdsEnv = process.env.ALLOY_BREAK_ON_DID ?? "";
+const debuggerIds = new Set<number>();
+debuggerIdsEnv.split(",").forEach((id) => {
+  const num = parseInt(id, 10);
+  if (!isNaN(num)) {
+    debuggerIds.add(num);
+  }
+});
+
+/** Parse the ALLOY_BREAK_ON_DID environment variable into a set of IDs. */
+export function parseBreakOnIds(): Set<number> {
+  const env = process.env.ALLOY_BREAK_ON_DID ?? "";
+  const ids = new Set<number>();
+  env.split(",").forEach((id) => {
+    const num = parseInt(id, 10);
+    if (!isNaN(num)) {
+      ids.add(num);
+    }
+  });
+  return ids;
+}
+
+/** Returns true if console tracing is enabled for the given phase (or any phase if not specified). */
+export function isConsoleTraceEnabled(phase?: string): boolean {
+  if (tracePhases.size === 0) return false;
+  if (!phase) return true;
+  const [area, subarea] = phase.split(".");
+  return tracePhases.has(area) || (subarea ? tracePhases.has(phase) : false);
+}
+
+if (tracePhases.size > 0) {
+  // eslint-disable-next-line no-console
+  console.log(
+    "Tracing enabled for phases:",
+    Array.from(tracePhases).join(", "),
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Trace phases
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Color {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export interface TracePhaseInfo {
+  area: string;
+  subarea: string;
+  bg: Color;
+}
+
+export const TracePhase = {
+  scope: {
+    update: { area: "scope", subarea: "update", bg: { r: 0, g: 255, b: 100 } },
+    create: { area: "scope", subarea: "create", bg: { r: 0, g: 150, b: 100 } },
+    delete: { area: "scope", subarea: "delete", bg: { r: 150, g: 0, b: 50 } },
+    copySymbols: {
+      area: "scope",
+      subarea: "copySymbols",
+      bg: { r: 0, g: 100, b: 100 },
+    },
+    moveSymbols: {
+      area: "scope",
+      subarea: "moveSymbols",
+      bg: { r: 0, g: 100, b: 100 },
+    },
+  },
+  symbol: {
+    update: { area: "symbol", subarea: "update", bg: { r: 0, g: 0, b: 255 } },
+    resolve: { area: "symbol", subarea: "resolve", bg: { r: 0, g: 0, b: 200 } },
+    create: { area: "symbol", subarea: "create", bg: { r: 0, g: 0, b: 150 } },
+    flow: { area: "symbol", subarea: "flow", bg: { r: 0, g: 0, b: 100 } },
+    addToScope: {
+      area: "symbol",
+      subarea: "addToScope",
+      bg: { r: 0, g: 0, b: 50 },
+    },
+    instantiate: {
+      area: "symbol",
+      subarea: "instantiate",
+      bg: { r: 0, g: 0, b: 25 },
+    },
+    clone: { area: "symbol", subarea: "clone", bg: { r: 0, g: 0, b: 25 } },
+    delete: { area: "symbol", subarea: "delete", bg: { r: 100, g: 0, b: 100 } },
+    removeFromScope: {
+      area: "symbol",
+      subarea: "removeFromScope",
+      bg: { r: 50, g: 0, b: 50 },
+    },
+  },
+  resolve: {
+    success: {
+      area: "resolve",
+      subarea: "success",
+      bg: { r: 0, g: 255, b: 0 },
+    },
+    pending: {
+      area: "resolve",
+      subarea: "pending",
+      bg: { r: 255, g: 255, b: 0 },
+    },
+    failure: {
+      area: "resolve",
+      subarea: "failure",
+      bg: { r: 100, g: 50, b: 50 },
+    },
+  },
+  effect: {
+    schedule: {
+      area: "effect",
+      subarea: "schedule",
+      bg: { r: 100, g: 100, b: 0 },
+    },
+    track: { area: "effect", subarea: "track", bg: { r: 75, g: 75, b: 0 } },
+    trigger: { area: "effect", subarea: "trigger", bg: { r: 50, g: 50, b: 0 } },
+    effectAdded: {
+      area: "effect",
+      subarea: "effectAdded",
+      bg: { r: 75, g: 100, b: 0 },
+    },
+    effectUpdated: {
+      area: "effect",
+      subarea: "effectUpdated",
+      bg: { r: 75, g: 75, b: 0 },
+    },
+    refAdded: {
+      area: "effect",
+      subarea: "refAdded",
+      bg: { r: 100, g: 75, b: 0 },
+    },
+  },
+  render: {
+    worker: { area: "render", subarea: "worker", bg: { r: 100, g: 50, b: 0 } },
+    appendChild: {
+      area: "render",
+      subarea: "appendChild",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    appendTextNode: {
+      area: "render",
+      subarea: "appendChild.textNode",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    appendCachedFragment: {
+      area: "render",
+      subarea: "appendChild.cachedFragment",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    appendCustomContext: {
+      area: "render",
+      subarea: "appendChild.customContext",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    appendPrintHook: {
+      area: "render",
+      subarea: "appendChild.printHook",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    appendComponent: {
+      area: "render",
+      subarea: "appendChild.component",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    appendMemo: {
+      area: "render",
+      subarea: "appendChild.memo",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+    renderEffect: {
+      area: "render",
+      subarea: "renderEffect",
+      bg: { r: 100, g: 50, b: 0 },
+    },
+  },
+} as const;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Console formatting utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TextFormat {
+  fg?: Color;
+  bg?: Color;
+  bold?: boolean;
+}
+
+export function colorText(text: string, fmt?: TextFormat): string {
+  if (!fmt) return text;
+  const codes: string[] = [];
+  if (fmt.bold) codes.push("1");
+  if (fmt.fg) codes.push(`38;2;${fmt.fg.r};${fmt.fg.g};${fmt.fg.b}`);
+  if (fmt.bg) codes.push(`48;2;${fmt.bg.r};${fmt.bg.g};${fmt.bg.b}`);
+  if (codes.length === 0) return text;
+  return `\x1b[${codes.join(";")}m${text}\x1b[0m`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Low-level trace API
+// ─────────────────────────────────────────────────────────────────────────────
+
+let traceCount = 0;
+
+function shouldTracePhase(area: string, subarea: string): boolean {
+  return (
+    isConsoleTraceEnabled(area) || isConsoleTraceEnabled(area + "." + subarea)
+  );
+}
+
+function shouldTrace(phase: TracePhaseInfo): boolean {
+  return shouldTracePhase(phase.area, phase.subarea);
+}
+
+export function traceType(phase: TracePhaseInfo): string {
+  return `${phase.area}:${phase.subarea}`;
+}
+
+export function logDevtoolsMessage(
+  message: ServerToClientMessage | DevtoolsMessage,
+) {
+  if (!isConsoleTraceEnabled()) return;
+  const type = String(message.type ?? "");
+  const colonIndex = type.indexOf(":");
+  if (colonIndex === -1) return;
+  const area = type.slice(0, colonIndex);
+  const subarea = type.slice(colonIndex + 1);
+  if (!area || !subarea) return;
+  if (!shouldTracePhase(area, subarea)) return;
+  // eslint-disable-next-line no-console
+  console.log("devtools:", message.type, message);
+}
+
+/**
+ * Emit a devtools message. Logs to console if tracing is enabled for the
+ * message's area, and broadcasts over the WebSocket if devtools are connected.
+ *
+ * Accepts both strictly-typed protocol messages and loosely-typed trace
+ * messages (which construct the type string dynamically).
+ */
+export function emitDevtoolsMessage(
+  message: ServerToClientMessage | DevtoolsMessage,
+) {
+  logDevtoolsMessage(message);
+  if (!isDevtoolsEnabled()) return;
+  broadcastDevtoolsMessage(message as DevtoolsMessage);
+}
+
+/**
+ * Low-level trace function for emitting console output.
+ * Use the `debug` object methods for most use cases.
+ */
+export function trace(
+  phase: TracePhaseInfo,
+  cb: () => string,
+  triggerIds: Set<number> = new Set(),
+): void {
+  if (shouldTrace(phase)) {
+    if (triggerIds.size === 0) {
+      const id = traceCount++;
+      triggerIds.add(id);
+      if (debuggerIds.has(id)) {
+        // eslint-disable-next-line no-debugger
+        debugger;
+      }
+    }
+
+    const areaTag = ` ${phase.area}:${phase.subarea} `;
+    const message = untrack(cb);
+    // eslint-disable-next-line no-console
+    console.log(
+      colorText(areaTag, { ...phase, bold: true }) +
+        " " +
+        colorText("[" + [...triggerIds].join(",") + "]", {
+          fg: { r: 50, g: 50, b: 50 },
+        }) +
+        " " +
+        message +
+        "\n",
+    );
+  }
+
+  if (isDevtoolsEnabled()) {
+    broadcastDevtoolsMessage({
+      type: traceType(phase),
+      triggerIds: [...triggerIds],
+    });
+  }
+}